Issue 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.*

Durable output contracts

An agent brief must capture the issue's goal, verified context, acceptance criteria, constraints, reproduction or validation commands, affected paths, and remaining unknowns. An out-of-scope record belongs in .out-of-scope/ and must record the request, decision, rationale, date, and conditions that would justify reconsideration. Use repository-provided templates when they exist.

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

Every triaged issue should carry exactly one category role and one state role. 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.

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.

Workflow

Step 1: show-attention

Interpret the user's invocation and fetch pending issues that need immediate action from the issue tracker. Present three buckets sorted 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.

Show counts and a one-line summary per issue, then let the maintainer select which one to proceed with.

Step 2: gather-context [depends_on: show-attention]

For triaging a specific selected issue, gather full system context:

• Read Tracker: Load the full issue body, comments, labels, reporter, and dates. Parse prior triage notes to prevent re-asking resolved questions.
• Search Episodic Memory: Invoke the kg_memory_recall MCP tool (searching Episodic Memory) to find similar triaged issues from past runs.
• Read Out-of-Scope Files: Check local .out-of-scope/*.md files and surface any prior rejections resembling this issue.
• Glossary Check: Explore the codebase using the project's domain glossary, respecting any active ADRs.

Step 3: blast-radius-repro [depends_on: gather-context]

Attempt reproduction and analyze systemic dependencies (bugs only):

• Reproduction: Read the reporter's steps, trace the relevant files, and run tests or reproduction scripts.
• Transitive Analysis: Localize the bug to a component, then run the kg_blast_radius MCP tool to map all transitive dependencies and proactively flag potential downstream regressions.

Step 4: recommend [depends_on: blast-radius-repro]

Formulate initial recommendations for the maintainer:

• Recommend: Tell the maintainer your category (bug or enhancement) and state recommendation with clear reasoning.
• Diagnostic Summary: Provide a brief codebase summary explaining the context of the issue.

Step 5: grill-details [depends_on: recommend]

Grill the reporter or maintainer if the issue lacks definition:

• Interactive Grilling: If the issue needs fleshing out, run an interactive /grill-with-docs session using docs to get exact requirements.

Step 6: apply-outcome [depends_on: grill-details]

Apply the outcome and update the issue tracker:

• ready-for-agent: Post a comprehensive comment using the durable agent brief contract above.
• ready-for-human: Post a similar agent brief structure, noting why it cannot be delegated.
• needs-info: Post triage notes using the template below.
• wontfix (bug): Write a polite explanation and close the issue.
• wontfix (enhancement): Write to .out-of-scope/, link to it in a comment, and close.

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

Step 7: quick-override [depends_on: none]

Provide a quick override bypass path:

• Quick State Override: If the maintainer invokes with a direct command like "move #42 to ready-for-agent", trust them, confirm what you are about to do, and apply the role directly without running the full triage loop.