分诊

它的作用¶

triage 会处理你项目跟踪器中的工单。它让每个工单经过一个由 分诊角色（一个类别角色和一个状态角色）组成的小型状态机。每个工单最终会成为一份代理就绪简报、一个向报告者提出的具体问题，或一个已关闭且记录了原因的工单。

它只适用于你没有创建的工单。也就是说，原始的 bug 报告、传入的功能请求，或一个不请自来的外部 pull request：这些工作从外部进入跟踪器，无论报告者留下时是什么形态。来自 to-tickets 的 工单 已经是代理就绪的，因此如果你对它们运行 triage，就会浪费已有工作。规则很简单：/triage 只用于传入的工单，而不是你自己创建的工单。

它也与手动打标签不同，因为它会给出建议，然后等待。它会给出它的类别和状态判断及理由，外加它在代码库中发现的内容，并且在你指示之前不会应用任何内容。

何时使用¶

你通过输入 /triage 来调用它，然后用自然语言描述你想要什么。代理 不会主动使用它。示例：“给我看任何需要我关注的内容”、“我们来看看 #42”、“把 #42 移到 ready-for-agent”。

前置条件¶

triage 会读取和写入你的工单跟踪器，因此 setup-matt-pocock-skills 必须先配置该跟踪器及其标签词汇表。下面的角色名称是规范的。你跟踪器中的标签字符串可能不同，而 setup 会提供映射。如果你的跟踪器已经精确使用规范名称，则你无需映射，也无需设置。

跟踪器配置还会决定外部 pull request 是否算作请求入口，以及谁算作外部。该标志默认关闭，且 setup 不再询问它。要将 PR 纳入范围，请在 docs/agents/issue-tracker.md 中将其打开。

状态机¶

每个经过分诊的条目最终都恰好拥有一个类别角色和一个状态角色。有两个类别：bug（某处坏了）和 enhancement（新功能或改进）。有五个状态：

这就是全部词汇。每个条目恰好一个状态角色的规则让查询保持简单。状态也是 技能 中最常被请求的领域。用户曾请求一个用于已指定但被另一个工单阻塞的工作的状态、一个用于等待未来触发器的工作的 deferred 状态，以及一个终态 implemented 状态。这些都没有发布。见下文的问题。

wontfix 有三种情况。区别很重要，因为其中只有一种会写入知识库：

.out-of-scope/ 为每个被拒绝的概念保存一个 markdown 文件，而不是为每个工单保存一个。每个文件都是一份简短的设计文档，而不是数据库行。它说明被拒绝的是什么、为什么，并列出所有提出该请求的工单。triage 在评估任何内容之前会读取整个目录。它按概念匹配，而不是按关键词匹配，因此 “夜间主题” 会匹配 dark-mode.md。当它找到匹配项时，它会向你展示旧决定，并询问你是否仍然同意，而不是从头再次争论该请求。

在生成简报前进行验证¶

在任何 追问 之前，triage 会检查该声明是否成立。对于 bug，它会按照报告者的步骤复现它。对于 PR，它会检出分支并运行相关测试。然后它会报告三种结果之一：

• 已确认，并附带代码路径。
• 无法复现。
• 细节不足以尝试。这是最强的 needs-info 信号。

在同一轮中，它会针对代码库运行另外两项检查。冗余检查会询问该功能是否已实现，并按领域概念搜索，而不是按报告者的措辞搜索。先前拒绝检查会询问 .out-of-scope/ 是否已经表示拒绝。这两项检查都很廉价，任一命中都会产生 wontfix。

所有这些工作都让一种产物变得有价值：代理简报。这是 triage 在工单移动到 ready-for-agent 时发布的结构化评论。在 triage 发布它之后，简报就是契约，而原始报告只是上下文。简报是持久的而非精确的，因为一个工单可能在代码变化期间停留在 ready-for-agent 数周。因此，简报会指明类型、签名和行为契约，而从不指明文件路径或行号。已确认的复现比猜测能形成强得多的简报。

PR 是附带了代码的 issue¶

如果跟踪器将外部拉取请求视为请求入口，它们会经过同一套机制，使用相同的类别、状态和转换。这些状态适用于 diff。ready-for-agent 表示已附带简报，并且代理应对代码采取下一步行动。ready-for-human 表示可以有人来合并它。PR 上的简报描述的是对现有 diff 还需做些什么，而不是如何从零开始构建它。

Discovery 只显示外部 PR，因为协作者进行中的分支不属于 triage 工作。这个筛选仅适用于 discovery。如果你明确指定某个 PR，无论作者是谁，triage 都会处理它。

常见问题¶

我运行了 /to-spec 和 /to-tickets，现在那些工单就那样放着，处于未 triage 状态。我需要再对它们运行 /triage 吗？ 不需要。它们已经是可供代理接手的了。to-tickets 在发布这些工单时会应用 ready-for-agent 标签，因此 AFK runner 无需再经过一轮就会接手它们。遇到这个问题的用户当时运行了 spec 流程，并在输出中看到了 needs-triage，而他们的 AFK runner 忽略了所有内容。triage 是来自外部工作的入口。spec 流程是你自己启动的工作的通道。两者在 ready-for-agent 处汇合，而不是在此之前。

现在既然有了 to-spec → to-tickets → implement 流程，triage 还有用吗？ 只有当你有外部进来的工作才需要。triage 比那个流程更早，而且职责不同：它负责处理其他人提交的报告。如果你的跟踪器里所有内容都来自你自己的规划，你很少会用到它。如果你维护任何公开项目，或者你的团队会给你提交 bug，那么这个工作就从这里开始。它的主要用途是接纳外部贡献者提交 issue 的开源仓库。

代理尝试应用 ready-for-agent，但 gh 提示该标签不存在。 这是一个已知的未修复 bug（#616）。setup-matt-pocock-skills 会把标签词汇写入 docs/agents/triage-labels.md，但不会在你的跟踪器中创建这些标签。请自行用 gh label create 或跟踪器的 UI 一次性创建五个状态标签和两个类别标签，错误就会消失。该 issue 链接到了一个尚未合并的社区修复分支。

五个状态不够用。那 blocked、deferred 或 implemented 呢？ 这是关于该技能收到反馈最多的缺口。它有三种形式：

• 一个已被完整定义，但需要等另一个 issue 关闭的 issue（#139）。报告者说，在这种情况下 ready-for-agent “技术上没错”但具有误导性，因此代理会接手它然后卡住。
• 打算做但需要等待触发条件的未来工作，因此目前还不可执行（#297）。
• 一个用于“已实现，等待验证”的终态。如果没有它，AFK runner 可能会把已经完成的工单再次加入队列。

blocked 这种情况被认可为真实存在，但名称尚未确定（blocked 还是 paused）。这些功能都尚未发布。作为变通方案，人们会在类别标签旁额外添加一个仓库本地的标签。这样状态位就保存了一个准确的值，但该技能并不知道这个额外标签。一个社区 fork 走得更远，增加了 needs-slicing、tracking 和工作量标签。这确实有效，但它属于那个 fork，而不是这个技能。

这和 /diagnosing-bugs 有什么不同？ 这里的验证步骤是刻意保持浅层的。它回答的是“这是否真实，以及大致位于哪里”，而不会寻找根本原因。如果按照报告者的步骤几分钟内无法复现 bug，请使用 needs-info；如果你现在就想调查，可以使用 diagnosing-bugs。目前这两个技能的文档都没有提到对方。有用户反馈了这个缺口，目前仍未解决。

我能让它指向我整个 backlog 然后运行吗？ 你可以这样要求，但要注意它会读取什么。“显示需要关注的内容”这一步只是一个用于选择的低成本列表。你选择一个 issue，然后 triage 会收集该 issue 的完整上下文。如果你让它一次性处理二十个 issue，代理可能会把那个低成本列表当作唯一证据，而不会告诉你。该列表返回 issue 正文，但不返回评论。恰好有一位用户遇到过这种情况。有三个 issue 的评论里已经写着“已修复，建议关闭”，但这三个 issue 却都生成了新的代理简报。如果要批量处理，请明确说明它必须阅读每个 issue 的评论。

它能与 Linear 或除 GitHub Issues 以外的其他工具一起使用吗？ 可以。跟踪器是配置项，而不是硬编码的假设。人们会针对 Linear（通过 linear CLI）、GitLab，以及 .scratch/ 目录下的纯 markdown 文件运行它。一种常见的分工是：Linear 用于 issue 和规划，GitHub 用于代码和 PR。那么，提到“issue tracker”的技能就映射到 Linear，提到“PR”的技能就映射到 GitHub。本地 markdown 跟踪器有一个未修复的模板 bug：生成的文件可能包含两遍验收标准，一次在顶层，一次在代理简报内部（#200）。

它正常工作的表现¶

• 它处理的每个条目最终都恰好有一个类别角色和一个状态角色，绝不会为零，也绝不会出现两个相互冲突的状态。
• 它会给出带有理由的建议然后停止，而不会给 issue 重新打上标签就继续处理。
• 在一切进入 ready-for-agent 之前，它就已经复现了 bug，或者检出并运行了 PR。
• 它写出的简报会指明类型和行为，并且不包含文件路径和行号。
• 当你六个月前拒绝的请求再次出现时，它会告诉你并引用当时的理由，而不是重新进行 triage。
• 它发布的每条评论都以 > *This was generated by AI during triage.* 开头。

它适用于哪里¶

triage 是一个入口，而不是主链路中的一步。主流程从你产生的一个想法开始（grill、spec、tickets、implement、review）。triage 是面向来自他人工作的并行通道。两条通道最终都在同一处汇合：一个带有 ready-for-agent 标签并附有简报的 issue。implement 会用与接收来自 to-tickets 的工单相同的方式接手它。当某个请求需要更多细节，triage 才能为其编写简报时，triage 会同时运行 grilling 和 domain-modeling，一次只问一轮问题，从而在做出决策时将它们记录到 GLOSSARY.md 和 ADR 中。当你不确定自己处于哪条通道时，ask-matt 会为你指路。