triage：把混乱待办变成智能体可执行的工作

作用

triage 会逐项处理项目 Tracker 中的 Issue，让每一项都经过一个由 triage 角色 构成的小型状态机——其中包括一个类别角色和一个状态角色——最终留下可供 Agent 直接执行的 Brief、一个向报告者提出的具体问题，或一条已经关闭且记录了原因的 Issue。

它只用于那些 并非由你创建的 Issue。原始 Bug 报告、新收到的功能请求、没有预告便突然出现的外部 Pull Request——也就是从外部进入 Tracker，并保持报告者原始提交形态的工作。 这些 由 to-tickets 生成的 Tickets 在设计上已经可以交给 Agent 直接执行，再对它们运行 triage 充其量只是浪费时间。规则非常明确： /triage 只处理传入的 Issue，不处理你自己创建的 Issue。

它与手动添加 Label 的第二个区别是：它会提出建议，然后等待。它会说明建议采用的类别和状态及其理由，并汇报在代码库中的发现；在你发出指示前，它不会应用任何更改。

何时使用它

你需要输入 /triage 来调用它，然后用自然语言描述你的需求—— 智能体 不会自行启用它。例如：“显示所有需要我关注的内容”“我们看看 #42”“把 #42 移到 ready-for-agent”。

前置条件

triage 会读取并写入你的 Issue Tracker，因此必须先由 setup-matt-pocock-skills 配置好 Tracker 及其 Label 词汇。下面的角色名称是 规范；你的 Tracker 中使用的 Label 字符串可能不同，setup 所提供的正是这种映射。如果 Tracker 已经完全采用规范名称，就无需映射，也无需设置。

Tracker 配置还决定外部 Pull Request 是否属于请求入口，以及哪些人算作外部人员。这个开关默认关闭，也不再是 setup 过程中的问题——如果希望把 PR 纳入范围，请在 docs/agents/issue-tracker.md 中将其开启。

状态机

每个经过 triage 的项目最终都恰好带有一个类别角色和一个状态角色。类别有两个： bug （某些内容发生故障）和 enhancement （新功能或改进）。状态有五个：

以上就是全部词汇，而“恰好一个状态角色”这一不变量让查询保持简单。这也是 技能中收到改进请求最多的部分：用户希望增加第六种状态，用于规格已经明确、却被另一条 Issue 阻塞的工作；还希望为 deferred 这种等待未来触发条件的工作，以及终止态 implemented 增加状态。这些功能均未发布，详见下方常见问题。

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

.out-of-scope/ 会为每个遭到拒绝的 概念创建一份 markdown 文件，而不是每条 Issue 一份。它写成简短的设计文档，而不是数据库记录：说明拒绝了什么、为什么拒绝，以及曾经提出该需求的每条 Issue。 triage 会在评估任何内容之前读取整个目录，并按概念而不是关键词匹配——“night theme”可以匹配 dark-mode.md。匹配成功后，它会展示过去的决策，并询问你现在是否仍持相同看法，而不是从头重新争论这项请求。

编写 Brief 前先验证

在开始任何 追问审视, triage 之前，都会先检查相关主张是否真实成立。对于 Bug，它会按照报告者提供的步骤复现；对于 PR，它会 Check Out 分支并运行相关测试。随后，它会报告三种结果之一：确认存在，并给出代码路径；无法复现；或细节不足，无法尝试——最后一种结果本身就是最强烈的 needs-info 信号。

在同一轮处理中，它还会针对代码库执行另外两项检查—— 冗余 （是否已经实现？搜索依据是领域概念，而非报告者的具体措辞）和 过去是否拒绝过 （ .out-of-scope/ 中是否已经明确拒绝？）。两项检查成本都很低，一旦命中，都会产生一个 wontfix 结果。

所有这些工作都服务于一项高质量产物： Agent Brief，也就是 Issue 移入 ready-for-agent时发布的结构化评论。Brief 发布后，它就是契约，原始报告只作为上下文。Brief 的写法追求 持久 而非精确，因为 Issue 可能会在 ready-for-agent 中停留数周，而底层代码仍在变化。因此，Brief 会注明类型、签名和行为契约，绝不写文件路径或行号。基于确认复现编写的 Brief，远比基于猜测的 Brief 更有力。

PR 就是一条附带代码的 Issue

如果 Tracker 把外部 Pull Request 视为请求入口，它们会经过同一套状态机——类别、状态和转换都完全相同，只是各状态需要结合 diff 来理解： ready-for-agent 表示已经附上 Brief，应由 Agent 继续处理现有代码； ready-for-human 表示已经可以由人类合并。PR 上的 Brief 描述现有 diff 还需要完成哪些工作，而不是如何从零构建整个功能。

发现流程只会列出 外部 PR，因为协作者仍在开发中的分支不属于 triage 工作。这个筛选条件只用于发现阶段——如果明确指定一个 PR，无论作者是谁，它都会接受 triage。这里有一个不够顺滑之处：GitHub 模板中的外部 PR 列表命令会要求 gh pr list 返回 authorAssociation 字段，但 gh 并未公开该字段，因此原样执行这条命令会直接失败（#468）。

常见问题

我运行了 /to-spec 和 /to-tickets，但这些 Tickets 现在仍处于未 triage 状态。我需要对它们运行 /triage 吗？ 不需要。它们已经可以交给 Agent 执行—— to-tickets 在发布时就会添加 ready-for-agent Label，目的正是让 AFK Runner 无需再经过一轮处理即可接手。遇到这个问题的用户运行了 Spec 流程，在输出上看到了 needs-triage ，随后发现 AFK Runner 忽略了所有内容。 triage 是外部传入工作的入口；Spec 流程则是你自己发起工作的通道。两条通道会在 ready-for-agent汇合，而不是更早。

既然已经有了 triage 流程， to-spec → to-tickets → implement 现在还重要吗？ 只有存在传入工作时才重要。 triage 早于这条主干流程，承担的工作也不同：它是处理他人所提交报告的通道。如果 Tracker 中的一切都来自你自己的规划，你很少会打开它。如果你维护公开项目，或团队成员会向你提交 Bug，它就是前门。其主要用途是让开源 repo 接收外部贡献者提交的 Issue。

Agent 尝试添加 ready-for-agent 和 gh 却提示该 Label 不存在。 这是一个已知且尚未解决的 Bug（#616）。 setup-matt-pocock-skills 会把 Label 词汇写入 docs/agents/triage-labels.md，但不会在 Tracker 中创建这些 Label。请使用 gh label create 或 Tracker UI，自行一次性创建五个状态 Label 和两个类别 Label，问题就会消失。该 Issue 链接了一个社区修复分支，但尚未合并。

五种状态不够——blocked、deferred 或 implemented 怎么办？ 这是该 Skill 被报告最多的能力缺口，共有三种形式。第一种是 Issue 已经完整定义，却仍在等待另一条 Issue 关闭（#139）——报告者认为，此时使用 ready-for-agent “从技术上说没错”，却具有误导性，Agent 接手后只会撞墙。第二种是由触发条件控制、未来确实要做但当前还无法执行的工作（#297）。第三种是“已经实现，等待验证”的终止状态；缺少它时，AFK Runner 可能会把已经完成的 Tickets 重新加入队列。Matt 同意 blocked 场景确实存在，但尚未决定状态名称（blocked 与 paused）。这些功能均未发布。人们采用的变通方案是在类别 Label 之外添加 repo 本地的额外 Label，让规范状态槽位仍由一个如实反映情况的状态占据，代价是 Skill 并不知道这个额外 Label。一个社区衍生版本走得更远，增加了 needs-slicing, tracking 和 effort Label——这种做法可以工作，但属于该衍生版本，并非原 Skill 的能力。

这与 /diagnosing-bugs? 这里的验证步骤有意保持浅层——只需回答“问题是否真实存在，大致位于哪里”，而不是查明根因。如果按照报告者的步骤尝试几分钟后仍无法复现 Bug，诚实的做法是将其设为 needs-info，或者在希望立即深入追查时使用 diagnosing-bugs 。目前两个 Skills 的文本都没有提到对方；一位用户发现了这条接缝，它至今仍未解决。

我能让它直接处理整个 Backlog 吗？ 你可以提出这个要求，但要留意它实际读取了什么。“显示需要关注的内容”这一轮只会生成低成本列表，目的是供你 选择 ——你选中一项后，它才会为该项收集完整 上下文 。如果一次让它处理二十条 Issue，Agent 可能会悄悄退回到低成本列表，并把它作为证据基础；该列表会返回 Issue 正文，却不包含评论。一位用户就遇到了这种情况：三条 Issue 已经有评论注明“已经修复，建议关闭”，结果三条都被重新生成了 Agent Brief。如果要批量处理，请明确要求逐条读取每条 Issue 的评论。

它支持 Linear 或 GitHub Issues 之外的系统吗？ 支持——Tracker 来自配置，而不是硬编码假设。人们会将它用于 Linear（通过 linear CLI）、GitLab，以及 .scratch/下的纯 markdown 文件。一种常见分工是：Linear 用于 Issue 与规划，GitHub 用于代码和 PR；提到“Issue Tracker”的 Skills 映射到 Linear，提到“PR”的 Skills 映射到 GitHub。本地 markdown Tracker 存在一个尚未解决的模板 Bug，生成的文件可能重复包含两份验收标准：一份位于顶层，另一份位于 Agent Brief 内（#200）。

出现这些迹象，说明它运行正常

• 它处理的每一项内容最终都恰好拥有一个类别角色和一个状态角色——不会缺失，也不会同时存在两个彼此冲突的状态。
• 它会给出建议及其理由，然后停下来等待，而不是直接更改 Label 后继续处理。
• 任何内容进入 ready-for-agent.
• 它编写的 Brief 会注明类型与行为，不包含文件路径，也不包含行号。
• 六个月前遭到拒绝的请求再次出现时，它会指出这一事实并引用过去的拒绝理由，而不是重新进行 triage。
• 它发布的每条评论都以下面这句话开头： > *This was generated by AI during triage.*

它在流程中的位置

triage 是一个 入口，而不是主链中的某个步骤。主流程从你自己的构思出发——追问、编写 Spec、拆分 Tickets、实施、评审——而 triage 是处理外部传入工作的并行通道。它们会在同一个位置汇合：一条带有 Brief、并标记为 ready-for-agent 的 Issue； implement 会像接手由 to-tickets生成的 Ticket 一样接手它。如果一项请求在编写 Brief 之前仍需进一步明确， triage 会同时运行 追问审视 和 domain-modeling ，每次提出一轮问题，让决策在作出时立即写入 CONTEXT.md 和 ADR。如果不确定自己位于哪条通道， ask-matt 会为你选择路线。