Triage

Triage

Move issues on the project issue tracker through a small state machine of triage roles.

Every comment or issue posted to the issue tracker during triage must start with this disclaimer:

> *This was generated by AI during triage.*

Reference docs

• AGENT-BRIEF.md - how to write durable agent briefs
• OUT-OF-SCOPE.md - how rejected enhancements are recorded (ArkEnv: use docs/adr/, not a root .out-of-scope/ folder)

Roles

Two category roles:

• bug - something is broken
• enhancement - new feature or improvement

Five state roles:

• needs-triage - maintainer needs to evaluate
• needs-info - waiting on reporter for more information
• ready-for-agent - fully specified, ready for immediate implementation
• ready-for-human - needs a judgment call or design decision before implementation
• wontfix - will not be actioned

One exempt role:

• meta - living documents (dashboards, roadmaps) that do not require triage state labels.

Every triaged issue should carry exactly one category role and one state role, unless it is a meta issue. If state roles conflict, flag it and ask the maintainer before doing anything else.

These are canonical role names - the actual label strings used in the issue tracker may differ. The mapping should have been provided to you - run /setup-matt-pocock-skills if not.

State transitions: an unlabeled issue normally goes to needs-triage first; from there it moves to needs-info, ready-for-agent, ready-for-human, or wontfix. needs-info returns to needs-triage once the reporter replies. The maintainer can override at any time - flag transitions that look unusual and ask before proceeding.

Invocation

The maintainer invokes /triage and describes what they want in natural language. Interpret the request and act. 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

Query the issue tracker and present three buckets, oldest first, excluding any issues with the meta role:

1. Unlabeled - never triaged (and not meta).
2. needs-triage - evaluation in progress.
3. needs-info - re-evaluation needed if reporter activity has occurred since the last triage.

Show counts and a one-line summary per issue. Let the maintainer pick.

Triage a specific issue

1. Gather context. Read the full issue (body, comments, labels, reporter, dates). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the project's domain glossary, respecting ADRs in the area. Check docs/adr/ (and related closed issues) for prior rejections that resemble this issue — do not look for or create a root .out-of-scope/ directory in this repo (see OUT-OF-SCOPE.md).

2. Recommend. Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary relevant to the issue. Wait for direction.

3. Reproduce (bugs only). Before any grilling, attempt reproduction: read the reporter's steps, trace the relevant code, run tests or commands. Report what happened - successful repro with code path, failed repro, or insufficient detail (a strong needs-info signal). A confirmed repro makes a much stronger agent brief.

4. Grill (if needed). If the issue needs fleshing out, run a /grill-with-docs session.

5. Apply the outcome:

   • ready-for-agent - post an agent brief comment (AGENT-BRIEF.md).
   • ready-for-human - same structure as an agent brief, but note why it can't be delegated (judgment calls, external access, design decisions, manual testing).
   • needs-info - post triage notes (template below).
   • wontfix (bug) - polite explanation, then close.
   • wontfix (enhancement) - record in docs/adr/ when architectural; otherwise a closing comment is enough. Link the record from the issue, then close (OUT-OF-SCOPE.md). Never create .out-of-scope/ in ArkEnv.
   • needs-triage - apply the role. Optional comment if there's partial progress.

Quick state override

If the maintainer says "move #42 to ready-for-agent", trust them and apply the role directly. Confirm what you're about to do (role changes, comment, close), then act. Skip grilling. If moving to ready-for-agent without a grilling session, ask whether they want to write an 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

Capture everything resolved during grilling under "established so far" so the work isn't lost. Questions must be specific and actionable, not "please provide more info".

Resuming a previous session

If prior triage notes exist on the issue, read them, check whether the reporter has answered any outstanding questions, and present an updated picture before continuing. Don't re-ask resolved questions.