triage

name	triage
description	Triage issues through a state machine driven by triage roles. Use when user wants to create an issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow.

Triage

通过一组小型 triage roles state machine，在项目 issue tracker 中移动 issues。

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

> *This was generated by AI during triage.*

Reference docs

• AGENT-BRIEF.md — 如何写持久可用的 agent briefs
• OUT-OF-SCOPE.md — .out-of-scope/ knowledge base 如何工作

Roles

两个 category roles：

• bug — 某个东西坏了
• enhancement — 新功能或改进

五个 state roles：

• needs-triage — maintainer 需要评估
• needs-info — 等待 reporter 提供更多信息
• ready-for-agent — 已完整说明，准备给 AFK agent 接手
• ready-for-human — 需要人工实现
• wontfix — 不会处理

每个已 triage 的 issue 应该刚好携带一个 category role 和一个 state role。如果 state roles 冲突，标记出来并先询问 maintainer，再做其他事。

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

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

Invocation

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

• "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 — 需要重新评估。

显示每个 bucket 的数量，以及每个 issue 的一行摘要。让 maintainer 选择。

Triage a specific issue

1. Gather context. 读取完整 issue（body、comments、labels、reporter、dates）。解析任何之前的 triage notes，避免重新询问已解决的问题。使用项目 domain glossary 探索 codebase，并遵守相关 ADRs。读取 .out-of-scope/*.md，并指出任何与此 issue 相似的既往拒绝。

2. Recommend. 告诉 maintainer 你的 category 和 state 推荐及理由，并给出与 issue 相关的简短 codebase summary。等待指示。

3. Reproduce（仅 bugs）. 在任何 grilling 前尝试复现：读取 reporter 的步骤，追踪相关代码，运行 tests 或 commands。报告发生了什么：成功复现及 code path、复现失败，或细节不足（强烈的 needs-info 信号）。已确认复现会让 agent brief 更有力。

4. Grill（如果需要）. 如果 issue 需要进一步充实，运行一次 /grill-with-docs session。

5. Apply the outcome:

   • ready-for-agent — 发布 agent brief comment（AGENT-BRIEF.md）。
   • ready-for-human — 使用与 agent brief 相同的结构，但说明为什么不能委托（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。如果有部分进展，可选择 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” 下，避免工作丢失。问题必须具体且可执行，而不是 “please provide more info”。

Resuming a previous session

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