安装此技能
npx skills@latest add mattpocock/skills --skill=triage 然后在你的编码 agent 里输入 /triage 。
本页目录
它做什么
triage 逐条处理你项目的追踪器（tracker）上的 issue。它让每一个穿过一个由**分诊角色（triage roles）**组成的小状态机（state machine）：一个类别角色（category role）和一个状态角色（state role）。每个 issue 最终成为一份 agent 就绪（agent-ready）的简报（brief）、一个给报告者的具体问题，或者一个带着记录下来的原因被关闭的 issue。
它只用于不是你创建的 issue。那意味着原始的 bug 报告、进来的功能请求，或者一个没打招呼就出现的外部 PR（pull request）：从外部进入追踪器的工作，不管报告者把它留成什么形状。来自 to-tickets 的工单（Tickets） 已经是 agent 就绪的，所以如果你对它们跑 triage，你就浪费了那项工作。规则很简单：/triage 只用于进来的 issue，不用于你自己创建的 issue。
它也和手工打标签不同，因为它先推荐、然后等待。它把类别与状态的判断连同理由，以及它在代码库里发现的东西一起给你，在你告诉它之前什么都不应用。
什么时候用它
你输入 /triage，然后用平实的语言描述你想要什么。agent 不会主动去拿它。例子：「给我看任何需要我注意的东西」、「我们看看 #42」、「把 #42 移到 ready-for-agent」。
| 你有什么 | 该去哪里 |
|---|---|
| 一个装满别人原始报告的追踪器 | /triage |
| 你自己一个粗略的主意，什么都还没写下来 | grill-with-docs |
| 一场已经谈定、要变成一份规范文档（spec）的对话 | to-spec |
| 一份要拆成 agent 就绪工单的规范文档 | to-tickets |
| 一个已经确认、需要根因而不是标签的 bug | diagnosing-bugs |
前提条件
triage 读写你的 issue 追踪器（issue tracker），所以 setup-matt-pocock-skills 必须先配置好那个追踪器及其标签词汇。下面的角色名称是规范名称。你追踪器里的标签字符串可能不同，而 setup 提供映射。如果你的追踪器已经原样使用这些规范名称，你就没有什么要映射，也没有什么要配置。
追踪器配置还决定外部 PR 是否算作一个请求面（request surface），以及谁算作外部。那个开关默认关闭，而 setup 不再询问它。要把 PR 纳入范围，就在 docs/agents/issue-tracker.md 里打开它。
状态机
每一个被分诊的条目最终都恰好拥有一个类别角色和一个状态角色。有两个类别：bug（有东西坏了）和 enhancement（新功能或改进）。有五个状态：
| 状态 | 意味着 |
|---|---|
needs-triage | 你需要评估它。一个没有标签的 issue 通常先落到这里。 |
needs-info | 在等报告者。他们回复后回到 needs-triage。 |
ready-for-agent | 完整写清楚了，附有一份 agent 简报（agent brief）。一个离开键盘（AFK） agent 可以接手它。 |
ready-for-human | 同样的简报，外加为什么 agent 做不了：判断、外部访问、手工测试。 |
wontfix | 已关闭，原因已记录。 |
这就是整套词汇。每个条目恰好一个状态角色的规则让查询保持简单。这些状态也是这个技能（skill）被要求最多的地方。用户要求过为「已经写清楚但被另一个 issue 阻塞」的工作加一个状态、为等待未来触发器的工作加一个 deferred 状态、以及一个终结性的 implemented 状态。这些一个都没有发布。见下面的问题。
wontfix 有三种情况。区别要紧，因为其中只有一种会写进知识库：
| 你关闭它的原因 | 会发生什么 |
|---|---|
| 已经实现了 | 一条指向该功能已经存在之处的评论。.out-of-scope/ 里什么都不放，因为它是一个已经构建的功能，不是被拒绝的，而那里的一个文件会破坏去重检查。 |
| 被拒绝的 bug | 礼貌的解释，然后关闭。 |
| 被拒绝的增强 | .out-of-scope/ 里的一个文件，从关闭评论里链接过去，然后关闭。 |
.out-of-scope/ 每个被拒绝的概念放一个 markdown 文件，而不是每个 issue 一个。每个文件是一份简短的设计文档，不是数据库里的一行。它说明什么被拒绝了、为什么，并列出每一个要求过它的 issue。triage 在评估任何东西之前会读完整个目录。它按概念匹配，而不是按关键词，所以「夜间主题」会匹配 dark-mode.md。当它找到匹配时，它给你看旧的决定，问你是否仍然同意它，而不是从头再为这个请求争论一遍。
在写简报之前先核实
在进入任何质询（grilling）之前，triage 会检查那个主张是否成立。对于一个 bug，它按报告者的步骤复现它。对于一个 PR，它检出那个分支并运行相关测试。然后它报告三种结果之一：
- 已确认，附上代码路径。
- 未能复现。
- 细节不足以尝试。这是现有的最强的
needs-info信号。
在同一趟里，它还会对代码库运行两项检查。**冗余检查（redundancy check）**问的是这个功能是否已经实现，并且按领域概念搜索，而不是按报告者的措辞。**先前拒绝检查（prior rejection check）**问的是 .out-of-scope/ 是否已经说了不。两项检查都很便宜，任意一项命中都会产出一个 wontfix。
所有这些工作都是为了做好一件产物：agent 简报。这是 triage 在 issue 移到 ready-for-agent 时贴出的结构化评论。在 triage 贴出它之后，这份简报就是契约，而原始报告只是上下文（context）。简报是耐久的，而不是精确的，因为一个 issue 可能带着 ready-for-agent 停留好几周，而代码在此期间变化。所以一份简报点名类型、签名和行为契约，从不写文件路径或行号。一次已确认的复现（repro）能做出比猜测强得多的简报。
一个 PR 就是一个附带代码的 issue
如果追踪器把外部 PR 当作一个请求面，它们就走同一台机器，使用同样的类别、状态和转换。这些状态作用于 diff。ready-for-agent 意味着附上了一份简报，agent 应该对代码走下一步。ready-for-human 意味着一个人可以合并它。PR 上的简报描述现有 diff 还剩下什么要做，而不是如何从零构建这个东西。
发现只显示外部的 PR，因为协作者进行中的分支不是分诊工作。那个过滤器只作用于发现。如果你明确点名一个 PR，triage 就会处理它，不管是谁写的。
常见问题
我跑了 /to-spec 和 /to-tickets，现在那些工单就摆在那里没分诊。我要对它们跑 /triage 吗？
不要。它们已经是 agent 就绪的。to-tickets 在发布它们时会打上 ready-for-agent 标签，所以一个 AFK 运行器会无需再走一趟就拾起它们。撞上这个问题的用户跑过规范文档流程，并在输出上看到 needs-triage，而他们的 AFK 运行器忽略了一切。triage 是外部进来的工作的入口（on-ramp）。规范文档流程（flow）是你自己启动的工作的车道。两条车道在 ready-for-agent 处会合，不是在此之前。
现在有了 to-spec → to-tickets → implement 这条流程，triage 还有意义吗？
只在你有进来的工作时。triage 比那条流程更老，做的是不同的工作：它处理别人提交的报告。如果你追踪器里的一切都来自你自己的规划，你会很少用到它。如果你维护任何公开的东西，或者你的团队把 bug 提给你，它就是那项工作的起点。主要用途是从外部贡献者那里接收 issue 的开源仓库。
agent 试图应用 ready-for-agent，而 gh 说这个标签不存在。
这是一个已知的未修复 bug（#616）。setup-matt-pocock-skills 把标签词汇写进 docs/agents/triage-labels.md，但不会在你的追踪器里创建这些标签。用 gh label create 或者追踪器的界面，自己一次性创建五个状态标签和两个类别标签，错误就会停止。那个 issue 链接到一个尚未合并的社区修复分支。
五个状态不够。阻塞、延后或已实现的情况怎么办？ 这是这个技能上被提交最多的缺口。它有三种形式：
- 一个 issue 已经完整写清楚，但在等另一个 issue 关闭（#139）。报告者说
ready-for-agent在那里「技术上是真的」，但会误导，所以一个 agent 会拾起它然后卡住。 - 未来要做的、有意为之但等待某个触发器的工作，所以它现在还不可行动（#297）。
- 一个「已实现、等待验证」的终结状态。没有它，一个 AFK 运行器会把已完成的工单再次排进队列。
被阻塞的情况被承认为真，但名字还没定（blocked 对 paused）。这些一个都没有发布。作为变通，人们在类别旁边加一个仓库本地的额外标签。状态槽位于是持有一个准确的值，但技能不知道那个额外标签。有一个社区 fork 走得更远，加了 needs-slicing、tracking 和投入级别（effort）标签。那能用，但它属于那个 fork，不属于这个技能。
它和 /diagnosing-bugs 有什么不同？
这里的验证步骤故意做得浅。它回答「这是真的吗，大概在哪里」，不去找根因。如果一个 bug 在几分钟内无法按报告者的步骤复现，就用 needs-info，或者如果你现在就想调查它，就用 diagnosing-bugs。两个技能的文本目前都没有提到对方。有用户报告了这个缺口，它仍然开着。
我能把它指向我整个待办清单，让它跑吗？
你可以问，但要留意它读什么。「显示需要关注的东西」那一趟只是一个用于选择的便宜列表。你挑一个 issue，然后 triage 才收集那个 issue 的完整上下文。如果你一次性跑二十个 issue，agent 可能把那个便宜列表当作它唯一的证据，而不告诉你。那个列表返回 issue 正文，但不返回评论。有一位用户正好撞上这一点。三个 issue 已经有一条评论说「已经修好，建议关闭」，而这三个都拿到了新的 agent 简报。对于批量处理，要明确说它必须读每个 issue 上的评论。
它能和 Linear 或 GitHub Issues 之外的东西一起用吗？
能。追踪器是配置，不是硬编码的假设。人们对 Linear（通过 linear CLI）、GitLab，以及 .scratch/ 下的普通 markdown 文件运行它。一种常见的分工是 Linear 管 issue 与规划，GitHub 管代码与 PR。那些说「issue 追踪器」的技能于是映射到 Linear，那些说「PR」的技能映射到 GitHub。本地 markdown 追踪器有一个开着的模板 bug：生成的文件可能包含两次验收标准（acceptance criteria），一次在顶层，一次在 agent 简报里（#200）。
它生效的标志
- 它碰过的每个条目最终都恰好有一个类别角色和一个状态角色，从不为零，也从不有两个互相冲突的状态。
- 它给你一条带理由的推荐，然后停下。它不会重新给 issue 打标签就走开。
- 在任何东西到达
ready-for-agent之前，它已经复现了 bug，或者检出并运行了 PR。 - 它写的简报点名类型和行为，并且不含文件路径、不含行号。
- 当你六个月前拒绝过的一个请求回来时，它告诉你并引用旧的理由，而不是再分诊一遍。
- 它贴出的每条评论都以
> *This was generated by AI during triage.*开头。
它在体系中的位置
triage 是一个入口，不是主链上的一步。主流程从你有的一个主意开始（质询、规范文档、工单、实现、审查）。triage 是给来自别人的工作的并行车道。两条车道在同一个地方结束：一个被打上 ready-for-agent 标签并附有简报的 issue。implement 拾起它的方式，和它拾起来自 to-tickets 的一个工单一样。当一个请求需要更多细节、triage 才能写简报时，triage 会一起运行质询和 domain-modeling，一轮问题接一轮问题，这样它在你做出决定时把决定记录进 GLOSSARY.md 和 ADR。当你不确定自己在那条车道上时，ask-matt 会为你路由。