triage

Triage

Move issues through the project issue tracker along a lean triage state machine.

Every comment or issue posted to the issue tracker during triage mustbegin with the following statement:

> *此内容由 AI 在分类过程中生成。*

Reference documents

• AGENT-BRIEF.md — how to write an agent brief that stands the test of time
• OUT-OF-SCOPE.md — .out-of-scope/ how the knowledge base works

Roles

Twocategoryroles:

• bug — something is broken
• enhancement — a new feature or improvement

Fivestateroles:

• needs-triage — the maintainer needs to evaluate
• needs-info — waiting for the reporter to provide more information
• ready-for-agent — the spec is complete and ready for an AFK agent to pick up
• ready-for-human — requires human implementation
• wontfix — will not be addressed

Every triaged issue should carry both one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything.

The above are canonical role names — the actual label strings used in the issue tracker may differ. The mapping should already be provided in configuration — if not, run /setup-matt-pocock-skills。

State transitions: an untagged issue usually first enters needs-triage; afterward it can move to needs-info、ready-for-agent、ready-for-human or wontfix。needs-info returns to needs-triageafter the reporter replies. The maintainer may override at any time — flag transitions that look unusual and ask before executing.

How to invoke

The maintainer invokes /triage and describes the need in natural language. Understand the intent, then execute. Examples:

• "Show me what needs my attention"
• "Let's look at #42"
• "Move #42 to ready-for-agent"
• "Which issues can an agent pick up first?"

Show what needs attention

Query the issue tracker, arranged into the following three categories, each sorted oldest first:

1. Untagged — never triaged.
2. needs-triage — evaluation in progress.
3. needs-info and the reporter has new activity since the last triage comment — needs re-evaluation.

Show the count for each category, along with a one-sentence summary of each issue. Let the maintainer choose.

Triage a specific issue

1. Gather context. Read the full issue (body, comments, labels, reporter, dates). Parse existing triage comments to avoid re-asking about already-resolved matters. Explore the codebase using the project domain glossary, and respect the ADRs in the relevant area. Read .out-of-scope/*.md, and present any past rejections similar to this issue.

2. Give a recommendation. Provide the maintainer with your category and state recommendation along with the reasoning, plus a brief summary of the codebase relevant to this issue. Wait for instructions.

3. Reproduce (bugs only). Before any deep review, try to reproduce: read the reproduction steps provided by the reporter, trace the relevant code, run tests or commands. Report the result — successfully reproduced with the code path explained, failed to reproduce, or insufficient information to reproduce (which in this case is a strong signal for adding needs-info . Confirming reproduction can greatly strengthen the quality of the agent brief.

4. Deep review (if needed). If the issue needs further refinement, run a /grill-with-docs session.

5. Implement the outcome:

   • ready-for-agent — post an agent brief comment (AGENT-BRIEF.md）。
   • ready-for-human — same structure as the agent brief, but note why it cannot be delegated to an agent (involves judgment calls, external access, design decisions, manual testing, etc.).
   • needs-info — post a triage comment (see template below).
   • wontfix(bug) — explain politely, then close.
   • wontfix(enhancement) — write to .out-of-scope/, link it in the comment, then close (OUT-OF-SCOPE.md）。
   • needs-triage — apply that role label. If there is partial progress, optionally attach a comment.

Quick status override

If the maintainer says "move #42 to ready-for-agent", trust them and just apply the role label. Confirm the action you are about to take (role change, comment, close), then execute. Skip the deep review. If moving to ready-for-agent and no deep review has been done, ask whether to write an agent brief.

Needs-info template

## 分类注释

**目前已确定：**

- 要点 1
- 要点 2

**仍需你提供（@报告人）：**

- 问题 1
- 问题 2

Group everything resolved during the review under "Determined so far" to avoid losing progress. Questions should be specific and actionable; do not say vaguely "please provide more information".

Resume a previous session

If there are already triage comments on the issue, read them, check whether the reporter has answered the unresolved questions, and present the updated overall picture before continuing. Do not ask again about issues that have already been resolved.