Triage（分诊）

在项目 issue tracker 上通过 small 分诊角色状态机移动 issue。

分诊期间发布到 issue tracker 的每条 comment 或 issue 必须以此 disclaimer 开头：

> *This was generated by AI during triage.*

Reference docs（参考文档）

• AGENT-BRIEF.md — 如何写 durable agent brief
• OUT-OF-SCOPE.md — .out-of-scope/ 知识库如何工作

Roles（角色）

两个 category 角色：

• bug — 某物 broken
• enhancement — 新 feature 或 improvement

五个 state 角色：

• needs-triage — maintainer 需 evaluate
• needs-info — 等 reporter 更多信息
• ready-for-agent — fully specified，ready for AFK agent
• ready-for-human — 需人工 implementation
• wontfix — 不会 action

每个 triaged issue 应携带 exactly one category role 与 one state role。若 state role 冲突，flag 并在做其他事前问 maintainer。

这些是 canonical role 名——issue tracker 中实际 label 字符串可能不同。Mapping 应该已提供——若没有，运行 /setup-matt-pocock-skills。

State transition：unlabeled issue 通常先到 needs-triage；从那里到 needs-info、ready-for-agent、ready-for-human 或 wontfix。needs-info 在 reporter 回复后回到 needs-triage。Maintainer 可随时 override——flag unusual transition 并在 proceed 前询问。

Invocation（调用）

Maintainer 调用 /triage 并用自然语言描述需求。Interpret 并 act。示例：

• 「Show me anything that needs my attention」
• 「Let's look at #42」
• 「Move #42 to ready-for-agent」
• 「What's ready for agents to pick up?」

Show what needs attention（展示需关注项）

Query issue tracker，present 三个 bucket，oldest first：

1. Unlabeled — 从未 triaged。
2. needs-triage — evaluation in progress。
3. needs-info 且自上次 triage notes 以来 reporter 有 activity — 需 re-evaluation。

Show count 与每 issue 一行 summary。让 maintainer 选。

Triage a specific issue（分诊特定 issue）

1. Gather context。 读完整 issue（body、comments、labels、reporter、dates）。Parse prior triage notes 以免 re-ask resolved question。用项目领域词汇表探索代码库，respect 区域 ADR。读 .out-of-scope/*.md，surface 任何 resemble 本 issue 的 prior rejection。

2. Recommend。 告诉 maintainer category 与 state recommendation 及 reasoning，加与 issue 相关的 brief codebase summary。等 direction。

3. Reproduce（仅 bug）。 任何 grilling 前 attempt reproduction：读 reporter step、trace 相关 code、run test 或 command。Report 结果——成功 repro 与 code path、失败 repro、或 detail 不足（strong needs-info signal）。Confirmed repro 使 agent brief 更强。

4. Grill（若需要）。 Issue 需 flesh out 时，run /grill-with-docs session。

5. Apply the outcome：
   - ready-for-agent — post agent brief comment（AGENT-BRIEF.md）。
   - ready-for-human — 与 agent brief 同结构，但 note 为何不能 delegate（judgment call、external access、design decision、manual testing）。
   - needs-info — post triage notes（下方 template）。
   - wontfix（bug）— polite explanation，然后 close。
   - wontfix（enhancement）— 写到 .out-of-scope/，comment 中 link，然后 close（OUT-OF-SCOPE.md）。
   - needs-triage — apply role。若有 partial progress 可 optional comment。

Quick state override（快速 state override）

Maintainer 说「move #42 to ready-for-agent」时，trust 并直接 apply role。Confirm 将做的（role change、comment、close），然后 act。Skip grilling。若到 ready-for-agent 且无 grilling session，问是否要写 agent brief。

Needs-info template

## Triage Notes

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

- point 1
- point 2

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

- question 1
- question 2

Grilling 期间 resolved 的一切 capture 在「established so far」下，工作不丢失。Question 必须 specific、actionable，而非「please provide more info」。

Resuming a previous session（恢复先前 session）

Issue 上有 prior triage notes 时，读取、检查 reporter 是否 answered outstanding question，present updated picture 再继续。Don't re-ask resolved question。