Lesson 0014 · Engineering · 只能人启动（user-invoked）· 流程课

triage：Issue tracker 的分诊状态机

周一早上你打开项目的 Issue tracker（放 issue 的地方：GitHub Issues、Linear， 或者本仓库里 .scratch/ 下的一套 markdown 约定），里面堆着三十条没处理过的东西： 两条 bug 报告、一个外部贡献者发来的 PR、一堆「能不能加个 dark mode」式的请求。 你不可能一条条凭感觉看过去。triage 就是干这个的： 它把每条 issue 推过一台小型状态机——先分类、再验证、必要时把请求烤（grill）成形， 最后在 issue 上留下一份 AFK agent（无人值守、自己干活的 agent）能直接接手的简报。 它由你手动输入 /triage 启动，AI 不会自己去碰它。 这节课你会学到：七个角色标签组成的状态机、处理单条 issue 的五步流水线、 它往 tracker 和仓库里写的每一样东西，以及行为不对时该去改哪个文件的哪一段。

1. 它在整个系统里站在哪

0001 的系统地图把 22 个 skill 分为主流程、入口（on-ramp）和独立件。triage 是入口之一：ask-matt 的原文是「Bugs and requests piling up → /triage」—— 外部世界不断往你的 tracker 里塞原始报告，triage 把这堆东西加工成 agent 能接的活，然后汇进主流程。它和另一条入口 diagnosing-bugs 的区别在于节奏： diagnosing-bugs 是「这个东西现在坏了，现在就修」； triage 是「队列在堆积，我定期来分拣一遍」。docs 把它叫作 tracker 的 periodic maintenance（定期保养）——报告堆起来时就跑一遍， 让 ready-for-agent 这一列永远可信。

它在链条上的准确位置是「tracker 的最前端，build 链的上游」： 它产出的 agent brief（agent 简报，后面第 7 节详讲）会被 implement 拾取， implement 内部再驱动 tdd 把活干完。 所以 triage 自己从不写实现代码——它写到 tracker 里的简报，就是下游一切的合同。

它还有一个方向上的近邻：to-spec。docs 的原话是， to-spec 把一场刚刚发生的对话变成 tracker 里的新内容（对话 → tracker）， 而 triage 处理的是已经落在 tracker 里的东西（tracker → 可执行的工作）。 两个 skill 读写同一个 tracker，方向正好相反。

路由原文：ask-matt/SKILL.md 的 On-ramps 一节 · 定位：docs/engineering/triage.md 的 Where it fits 一节 · 地图：0001

2. 调用方式与前置条件

2.1 只能你启动，AI 不会自己来

SKILL.md 的 frontmatter 里写着 disable-model-invocation: true， 同目录的 agents/openai.yaml 里写着 policy.allow_implicit_invocation: false。 两条加起来的意思是：这是一个 user-invoked（只能人启动）的 skill—— AI 在任何情况下都不应该自作主张去跑它。 想想也合理：分诊会往真实的 tracker 上写标签、发评论、关 issue， 这种对外副作用必须等你明确下令。

启动方式是输入 /triage 加一句自然语言的意图，skill 负责解释这句话并行动。 SKILL.md 给的例子：

• 「Show me anything that needs my attention」——给我看所有需要我操心的（走第 5 节的总览队列）
• 「Let's look at #42」——看某一条具体的 issue 或 PR（走第 6 节的五步流水线）
• 「Move #42 to ready-for-agent」——直接改状态（走第 6.6 节的快速通道，跳过面试）
• 「What's ready for agents to pick up?」——列出 agent 现在能接的活

2.2 前置条件：setup 必须先跑过

triage 要读写你的 Issue tracker，所以它依赖 setup-matt-pocock-skills（0002 讲过）事先写好的两份配置文件：

SKILL.md 原话：「这些映射应该已经提供给你了——如果没有，运行 /setup-matt-pocock-skills」。所以行为排查时， 「triage 贴的标签我 tracker 里根本没有」第一反应不是改 skill，而是去看那份映射表。

触发规则：skills/engineering/triage/SKILL.md frontmatter 与 Invocation 一节 · 隐式调用禁令：triage/agents/openai.yaml · 映射从哪来：setup-matt-pocock-skills/triage-labels.md · tracker 配置：setup-matt-pocock-skills/issue-tracker-github.md

3. 核心词汇：七个 Triage role 和状态机

CONTEXT.md 给过一个定义：Triage role（分诊角色）是分诊过程中贴到 issue 身上的规范状态机标签，每个角色通过 triage-labels.md 映射到 tracker 里的真实标签字符串。triage 一共用七个角色，分两族：

3.1 一条铁律：一个分类 + 一个状态

每条被分诊过的 issue 必须恰好携带一个 category role 和一个 state role—— 不能没有，也不能同时挂两个状态。如果发现状态角色冲突（比如同时贴着 needs-info 和 ready-for-agent），skill 的指令是： 指出来，先问维护者，再做任何其它事。 它不替你猜哪个状态是真的。

3.2 状态怎么流转

                 报告者回复了
        ┌─────────────────────────────┐
        ▼                             │
   （无标签） ──► needs-triage ──┬──► needs-info
                        │        │
                        │        ├──► ready-for-agent ──► agent brief 已挂上，
                        │        │                         implement 可拾取
                        │        ├──► ready-for-human ──► 等人来实现/合并
                        │        └──► wontfix ──► 关闭（理由写进评论，
                        │                          被拒绝的 enhancement 进 .out-of-scope/）
                        └── 维护者随时可以覆盖任何流转；
                            看起来不寻常的流转 → 先问再动

按 SKILL.md 的状态流转一节：一条没标签的 issue 通常先进 needs-triage；从那里流向四个终态或中间态之一； needs-info 在报告者回复之后回到 needs-triage 重新评估（这就是第 5 节总览队列第三个桶存在的原因）。 维护者在任何时候都能覆盖流转——但 skill 被要求「把看起来不寻常的流转标出来，先问再继续」。

角色与流转：triage/SKILL.md 的 Roles 一节 · 词汇定义：CONTEXT.md 的 Triage role 词条

4. PR 就是「带着代码的 issue」

如果你的 tracker 配置把外部 PR 当作请求入口（request surface），triage 对 PR 走的是同一台状态机：同样的分类角色、同样的状态、同样的流转。 SKILL.md 的原话是「a PR is an issue with attached code」—— 一个 PR 就是一条附了代码的 issue。差别只在状态的读法上： 对 PR 来说，状态是对着 diff（代码差异）读的——ready-for-agent 意思是「简报已挂上，agent 应该在这份 diff 的基础上继续推进」； ready-for-human 意思是「人可以来合并了」。

PR 规则：triage/SKILL.md 开头第二段与 Show what needs attention 一节 · 外部定义与编号解析：issue-tracker-github.md 的 Pull requests as a triage surface 一节 · 默认关闭：setup-matt-pocock-skills/SKILL.md 的 Section A

5. 总览队列：三个桶

你说「给我看看需要操心的东西」时，skill 查询 tracker，把结果分成三个桶， 每桶内部最老的排在最前：

1. Unlabeled（无标签）——从没被分诊过的；
2. needs-triage——评估进行到一半的；
3. needs-info 且自上次分诊笔记以来报告者有新活动——你等的答案来了，需要重新评估。

PR 在范围内时，外部 PR 也进这三个桶，每行打 [PR] 或 [issue] 标记。 展示形式是「数量 + 每条一行摘要」，然后由你挑先看哪条——skill 不替你排序优先级。 注意第三个桶的设计意图：needs-info 不是死状态，报告者一回复， 这条 issue 就自动浮回你的注意力里（对应第 3 节「回复后回到 needs-triage」的流转）。

6. 单条 issue 的五步流水线

这是整个 skill 的主干。你点名一条 issue（或从队列里挑了一条）之后， SKILL.md 规定五步按序走：

6.1 第一步：Gather context（收集上下文）

读完整的 issue 或 PR——正文、评论、标签、作者、日期；是 PR 就再读 diff。 解析所有历史分诊笔记，避免把已经回答过的问题再问一遍。 然后用项目的领域词汇表（CONTEXT.md）去探索代码库，尊重相关区域的 ADR （架构决策记录，0004 讲过）。探索时跑两个检查：

• Redundancy（冗余检查）——按领域概念（而不是请求的字面措辞） 搜一遍代码库：请求的行为是不是已经有人实现了？找到了，这就是一条「已实现的 wontfix」， 直接跳到第五步关闭它。skill 还被要求汇报你都看了哪些地方—— 「没搜到」必须附带搜索范围才有说服力。
• Prior rejection（既往拒绝检查）——读 .out-of-scope/*.md， 看这条请求像不像某个已经被拒绝过的概念（详见第 8 节）。

6.2 第二步：Recommend（给建议，然后等）

把你的分类建议、状态建议、推理过程，连同一段与请求相关的代码库摘要 （包括「这东西是不是已经实现了」）一起告诉维护者——然后停下来等指示。 docs 把这叫作「recommends and waits」：它给出带理由的判断，但只在你点头之后才动手。 这是 triage 和「凭感觉贴标签」最不一样的地方之一。

6.3 第三步：Verify the claim（验证说法）

在任何面试（grilling）开始之前，先验证 issue 里的说法站不站得住：

• 是 bug：按报告者给的步骤实际重现一遍；
• 是 PR：确认 diff 真的干了它声称的事——把分支 checkout 出来，跑相关的测试或命令。

结果分三种：confirmed（确认，附带指向具体代码路径）、failed （没复现出来）、insufficient detail（细节不够验证——这本身就是强烈的 needs-info 信号）。SKILL.md 特别强调： 一次被确认的验证会让后面写出来的 agent brief 强得多—— 「我按步骤复现了，断在 X 函数」和「报告者说坏了」是两种完全不同成色的简报。

6.4 第四步：Grill（必要时烤一烤）

如果请求还需要充实形状，skill 把 /grilling 和 /domain-modeling 两个 skill 一起拉进来： 一次只问一个问题，把请求烤成形；过程中磨尖领域术语，决策一落地就就地更新 CONTEXT.md 和 ADR。这就是 0003 讲的面试纪律和 0004 讲的领域建模纪律 在 tracker 场景下的复用——triage 自己不重新发明面试，它调用现成的两个 skill。 烤出来的每一点共识都要接住：第五步发 needs-info 时， 它们全部进「已确定事项」，不丢。

6.5 第五步：Apply the outcome（落地结果）

五种出口，各写各的东西：

6.6 快速通道：维护者直接下状态命令

你说「move #42 to ready-for-agent」时，skill 的指令是信任你： 直接应用角色，跳过收集、验证、面试整套流程。但有两条保留： 动手前先复述确认你将要做的事（改什么角色、发什么评论、关不关 issue）； 如果是没经过面试就进 ready-for-agent，要补问一句「要不要写一份 agent brief」。

6.7 needs-info 的分诊笔记模板

## Triage Notes

**What we've established so far:**

- point 1
- point 2

**What we still need from you (@reporter):**

- question 1
- question 2

两条硬要求：面试中敲定的一切放进「established so far」，让已经做掉的工作不丢； 问题必须具体、可行动——「please provide more info」这种空话被明文禁止。 这份笔记同时是下一次分诊的恢复点：SKILL.md 的 Resuming 一节规定， 只要 issue 上存在历史分诊笔记，重开时先读它、检查报告者有没有回答悬着的问题、 给出更新后的全貌，再继续——不许重复问已解决的问题。

6.8 每条评论的强制开场白

分诊期间发到 tracker 上的每一条评论、每一个新 issue，都必须以这行 disclaimer（免责声明）开头：

> *This was generated by AI during triage.*

这是对外透明义务：报告者和贡献者有权知道这条回复是 AI 在分诊过程中生成的。 漏掉它不是格式小瑕疵，是 SKILL.md 开头用 must 写的硬性规定。

五步流水线、快速通道、模板、免责声明、恢复规则： triage/SKILL.md 的 Triage a specific issue or PR、Quick state override、Needs-info template、Resuming a previous session 各节

7. AGENT-BRIEF.md：写给 AFK agent 的合同

第一个 sibling 文件 AGENT-BRIEF.md 讲的是 ready-for-agent 那一刻发出去的那条评论怎么写。开篇第一句定调：agent brief 是 AFK agent 工作时依据的 权威规格——issue 的原始正文和讨论只是背景，brief 才是合同。 原始讨论可能又乱又长，合同必须干净。对 issue 来说，brief 是「从零把东西建出来」； 对 PR 来说，brief 是「在这份已有 diff 上还剩什么」——补完它、堵上缺口、回应评审意见。

7.1 四条写作原则

7.2 模板骨架

## Agent Brief

**Category:** bug / enhancement
**Summary:** 一句话说清要发生什么

**Current behavior:**   现在是什么样（bug 就是坏掉的行为；enhancement 就是现状）
**Desired behavior:**   干完之后应该是什么样（含边界情况和出错条件）
**Key interfaces:**     要动的类型 / 函数签名 / 配置结构，以及为什么
**Acceptance criteria:** 可勾选的、逐条可独立验证的标准
**Out of scope:**       明确不改、不碰的东西

AGENT-BRIEF.md 还给了三份好示例（bug 版、enhancement 版、PR 版）和一份坏示例。 坏示例的罪名清单值得背下来：没分类、描述含糊（「the triage thing is broken」）、 引用了会过期的文件路径和行号、没有验收标准、没有范围边界、没写现状与期望的差别。 PR 版的差别只有一处：「Current behavior」描述的是 diff 的现状， brief 请 agent 把这份 diff 做完、修好，而不是从零开工。

原则、模板、四份示例：triage/AGENT-BRIEF.md

8. OUT-OF-SCOPE.md：.out-of-scope/ 拒绝知识库

第二个 sibling 文件 OUT-OF-SCOPE.md 讲的是被配置项目仓库根下 .out-of-scope/ 目录的玩法。它存的是被拒绝的功能请求的持久记录， 服务两个目的：

1. Institutional memory（机构记忆）——为什么拒绝，理由不随 issue 关闭而消失；
2. Deduplication（去重）——新 issue 撞上既往拒绝时，把旧决定端出来，而不是重新吵一遍。

8.1 文件长什么样

• 一个概念一个文件，不是一条 issue 一个文件。三条请求 dark mode 的 issue 归到同一个 dark-mode.md 下。
• 文件名用简短的 kebab-case（单词小写、连字符相连）：dark-mode.md、plugin-system.md——扫一眼目录名就知道拒绝过什么。
• 文风要放松可读，像一份小设计文档，不像数据库条目：段落、代码示例都可以上。
• 拒绝理由必须有实质：指向项目定位（「本项目专注 X，主题是下游消费者的事」）、技术约束（「支持它需要 Y，和我们的 Z 架构冲突」）、或战略决策（「我们选了 A 而不是 B，因为……」）。理由还必须耐放——「我们现在太忙」不是拒绝，是推迟，不许写进去。
• 文件末尾的 Prior requests 列表收集所有请求过这个概念的历史 issue 链接。

8.2 什么时候读、什么时候写

全部规则：triage/OUT-OF-SCOPE.md · 与第五步的衔接：triage/SKILL.md 的 Apply the outcome 一节

9. 会留下什么、用完接什么、想微调改哪里

9.1 副作用清单：它到底写/改了什么

9.2 依赖谁、被谁依赖

            setup-matt-pocock-skills（前置：tracker 配置 + 标签映射）
                              │
                              ▼
   原始 issue/PR ──►  /triage ──┬── 拉进 /grilling + /domain-modeling（第四步）
      （别人创建的）    │        └── 就地更新 CONTEXT.md / ADR
                       │
                       ├── ready-for-agent（挂着 agent brief）
                       │        ▼
                       │     /implement（内部驱动 /tdd）拾取并干活
                       ├── ready-for-human ──► 人来实现 / 合并
                       └── wontfix ──► .out-of-scope/（仅被拒的 enhancement）

   不喂给它：/to-tickets 切出来的 issue（出生即 agent-ready）
   方向近邻：/to-spec（对话 → tracker，和 triage 的 tracker → 工作 正好相反）

9.3 用完之后，下一步去哪

1. 队列清完了 → 看 ready-for-agent 列，挑一条开 /implement（它会内部驱动 tdd）；每条之间清上下文。
2. 分诊中发现请求其实很大、形状不清 → 别在分诊里硬做，把它当想法带进主流程：从 /grill-with-docs 开始走 0001 的主线。
3. 验证时发现是真 bug 而且你想现在就修 → 换 /diagnosing-bugs 那条入口（0015），分诊只负责分拣，不负责修。
4. 被 wontfix 的 PR 作者不服 → 指着 .out-of-scope/ 里的理由说话；要翻案就走 8.2 的 Reconsider 分支，删文件、重走分诊。

9.4 行为不对时，去改哪个文件的哪一段

10. 检索练习

先别往回翻，凭记忆答。选项长度刻意对齐，不会从版式泄题。答案以 SKILL.md 和两个 sibling 文件的原文为准。

11. 下一课与一手材料

本课主一手材料（请打开原文读，不要只背本页摘要）：

• skills/engineering/triage/SKILL.md —— 七个角色、状态流转、调用方式、三个桶、五步流水线、快速通道、分诊笔记模板、恢复规则、AI disclaimer。
• …/AGENT-BRIEF.md —— agent brief 的四条写作原则、模板、三份好示例与一份坏示例。
• …/OUT-OF-SCOPE.md —— .out-of-scope/ 知识库的文件格式、读写时机、维护者的三种回应。
• docs/engineering/triage.md —— 给人看的叙事版：「PR 是带代码的 issue / 先验证再写简报 / 它在链条上的位置」 （aihero.dev/skills-triage）。
• 上下游对照： ask-matt（On-ramps 一节：谁该喂给 triage、谁不该）· triage-labels.md（标签映射种子）· issue-tracker-github.md（PR 开关与「外部」定义）。

速查页（本课同步）： reference/triage.html

导航： 上一课 0013 code-review （implement 收尾时的两轴评审——分诊写出的简报最终会在那里被对照 Spec 轴检查）。 总览仍回 0001 系统地图； 前置配置见 0002 setup； 第四步拉进来的两个 skill 见 0003 grilling 与 0004 domain-modeling； 下游接力见 0011 implement 与 0012 tdd。

建议下一课（0015）： 0015 diagnosing-bugs —— 另一条「有东西坏了」的入口。分诊课上你学会了把 bug 报告分拣、验证、写成简报； 下一课学的是当你决定现在就修时，怎么先要一条会变红的反馈回路、 再用回归测试把 bug 锁死。两课共用「先验证、别猜」的纪律，正好连着读。