Triage

Triage

把项目 issue tracker 上的 issues 移动过一套小型 triage roles 状态机。

Triage 期间发布到 issue tracker 的每条 comment 或 issue 都必须以这个 disclaimer 开头：

> *This was generated by AI during triage.*

Reference docs

• AGENT-BRIEF.md — 如何编写 durable agent briefs
• OUT-OF-SCOPE.md — .out-of-scope/ knowledge base 如何工作

Roles

两个 category roles：

• bug — 某个东西坏了
• enhancement — 新 feature 或 improvement

五个 state roles：

• needs-triage — maintainer 需要评估
• needs-info — 等待 reporter 提供更多信息
• ready-for-agent — 完全规格化，ready for AFK agent
• ready-for-human — 需要 human implementation
• wontfix — 不会处理

每个 triaged issue 都应正好携带一个 category role 和一个 state role。如果 state roles 冲突，先标记并询问 maintainer，再做其他事。

这些是 canonical role names；issue tracker 中实际使用的 label strings 可能不同。Mapping 应该已经提供给你；如果没有，运行 /setup-matt-pocock-skills。

State transitions：未标记 issue 通常先进入 needs-triage；之后移动到 needs-info、ready-for-agent、ready-for-human 或 wontfix。Reporter 回复后，needs-info 回到 needs-triage。Maintainer 可以随时 override；对看起来不寻常的 transitions，要先标记并询问再继续。

Invocation

Maintainer 调用 /triage，并用自然语言描述想做什么。解释请求并行动。Examples：

• "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

查询 issue tracker，并按最旧优先展示三个 buckets：

1. Unlabeled — 从未 triaged。
2. needs-triage — evaluation in progress。
3. needs-info with reporter activity since the last triage notes — 需要重新评估。

展示 counts 和每个 issue 的一行 summary。让 maintainer 选择。

Triage a specific issue

1. Gather context. 读取完整 issue（body、comments、labels、reporter、dates）。解析任何 prior triage notes，避免重复询问已解决问题。使用项目 domain glossary 探索 codebase，并尊重该区域 ADRs。读取 .out-of-scope/*.md，并展示任何与此 issue 相似的 prior rejection。

2. Recommend. 告诉 maintainer 你推荐的 category 和 state，以及 reasoning，并附上与该 issue 相关的简短 codebase summary。等待指示。

3. Reproduce（bugs only）. 在任何 grilling 前尝试 reproduction：读取 reporter steps，追踪相关 code，运行 tests 或 commands。报告发生了什么：成功 repro 和 code path、repro 失败，或信息不足（强 needs-info 信号）。Confirmed repro 会生成强得多的 agent brief。

4. Grill（if needed）. 如果 issue 需要充实，运行 /grill-with-docs session。

5. Apply the outcome:

   • ready-for-agent — 发布 agent brief comment（AGENT-BRIEF.md）。
   • ready-for-human — 使用与 agent brief 相同的结构，但说明为什么不能 delegate（judgment calls、external access、design decisions、manual testing）。
   • needs-info — 发布 triage notes（template 见下）。
   • wontfix（bug）— 礼貌解释，然后 close。
   • wontfix（enhancement）— 写入 .out-of-scope/，从 comment 链接它，然后 close（OUT-OF-SCOPE.md）。
   • needs-triage — 应用 role。如果有 partial progress，可选择 comment。

Quick state override

如果 maintainer 说 "move #42 to ready-for-agent"，信任他们并直接应用 role。确认你即将做什么（role changes、comment、close），然后行动。跳过 grilling。如果在没有 grilling session 的情况下移动到 ready-for-agent，询问他们是否想写 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 中解决的所有内容捕获在 "established so far" 下，避免工作丢失。Questions 必须具体且 actionable，不要写 "please provide more info"。

Resuming a previous session

如果 issue 上存在 prior triage notes，读取它们，检查 reporter 是否回答了任何 outstanding questions，并在继续前展示 updated picture。不要重复询问已解决的问题。