Triage

Triage

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

If this repository treats external pull requests as a request surface (see the issue-tracker config), triage covers them too: a pull request is an issue with attached code — same roles, same states, same machine, with a few deltas marked "for a pull request" below. Resolve a bare issue identifier to an issue or pull request according to the tracker config.

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 the .out-of-scope/ knowledge base works

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 an AFK agent
• ready-for-human — needs human implementation
• wontfix — will not be actioned

For a pull request, the same states read against the attached code: ready-for-agent means a brief is attached and an agent should take the next step on the diff; ready-for-human means it is ready for a human to merge.

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

These are canonical role names — the actual label strings used in the issue tracker may differ. Resolve them through docs/agents/triage-labels.md. If the mapping is missing, stop and ask the maintainer to invoke setup-skills.

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:

1. Unlabeled — never triaged.
2. needs-triage — evaluation in progress.
3. needs-info with reporter activity since the last triage notes — needs re-evaluation.

When pull requests are in scope, include external pull requests in these buckets and tag each line [PR] or [issue]. Discovery surfaces only external pull requests; the tracker config defines who counts as external. A collaborator's in-flight pull request is not triage work. This filter is discovery-only; an explicitly named pull request is always triaged regardless of author.

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

Triage a specific issue or pull request

1. Gather context. Read the full issue or pull request: body, comments, labels, author, dates, and the diff for a pull request. Parse prior triage notes so resolved questions are not repeated. Explore the codebase using the project's domain glossary and respect ADRs in the area. Run two checks against the codebase:
   • Redundancy — search for an existing implementation of the requested behavior by domain concept, not just the request's wording, and report where you looked. If found, it is an already-implemented wontfix outcome in step 5.
   • Prior rejection — read .out-of-scope/*.md and surface any record that resembles this request.
2. Recommend. Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary relevant to the request, including whether it is already implemented. Wait for direction.
3. Verify the claim. Before any grilling, check that the claim holds up. For a bug, reproduce it from the reporter's steps. For a pull request, confirm the diff does what it claims by inspecting it and running the relevant tests or commands in an isolated worktree or another non-destructive checkout. Preserve unrelated user work. Report what happened: confirmed with a code path, failed, or insufficient detail. Insufficient detail is a strong needs-info signal.
4. Grill when needed. If the request needs fleshing out, apply the grilling and domain-modeling skills together — grill it into shape a frontier round at a time, sharpening domain terms and updating CONTEXT.md and ADRs inline as decisions land.
5. Apply the outcome:
   • ready-for-agent — post an agent brief comment using AGENT-BRIEF.md.
   • ready-for-human — use the same structure as an agent brief, but note why it cannot be delegated: judgment calls, external access, design decisions, or manual testing.
   • needs-info — post triage notes using the template below.
   • wontfix — close with a comment determined by the reason:
     • Already implemented — point to where the behavior lives. Keep it out of .out-of-scope/; that knowledge base is for rejected requests, not built ones.
     • Rejected bug — post a polite explanation, then close.
     • Rejected enhancement — write to .out-of-scope/, link it from a comment, then close using OUT-OF-SCOPE.md.
   • needs-triage — apply the role. Add a comment only when partial progress is worth preserving.

Quick state override

If the maintainer says "move #42 to ready-for-agent", trust them and apply the role directly. Still enforce exactly one category and one state; ask for the category only when it is missing and cannot be inferred safely. Confirm the role changes, comment, and closure behavior before acting. Skip grilling. If moving to ready-for-agent without a grilling session, ask whether they want 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 is not lost. Questions must be specific and actionable.

Resuming a previous session

If prior triage notes exist on the issue or pull request, read them, check whether the reporter answered any outstanding questions, and present an updated picture before continuing. Do not repeat resolved questions.