Triage

Triage

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

If this repo treats external pull requests as a request surface, triage covers them too — a PR is an issue with attached code, using the same roles and states.

Labels

The vocabulary lives in LABELS.md — read it before assigning. /spec and /ship read the same file, so it is the one place labels are defined.

Invocation

The maintainer invokes /triage and describes what they want. 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 tracker:

gh issue list --state open --json number,title,labels --limit 50

Present three buckets, oldest first:

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

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

Triage a specific issue or PR

1. Gather context. Read the issue or PR:

   gh issue view <n> --json title,body,comments,labels,state,parent
   gh issue list --search "in:title <keyword>" --json number,title --limit 5
   

   Check if it duplicates an existing issue.

   Read prd/glossary.md if it exists and use its vocabulary in the brief.

2. Categorise. Assign one type label: type:bug, type:feature, type:spec, type:ticket, type:docs, or type:chore.

3. Assess readiness. Can an agent pick this up as-is? Does it need more info from the reporter? Is it out of scope?

4. Assign status. Move to the appropriate status label. If status:ready-for-agent, write a brief (see below).

5. Assign priority. Ask the user or infer from impact.

6. Assign scope. Which area(s) does this touch?

7. Post to the tracker.

   gh issue edit <n> --add-label "<labels>"
   gh issue comment <n> --body "> *This was generated by AI during triage.*\n\n<brief>"
   

Writing agent-ready briefs

When an issue moves to status:ready-for-agent, attach a brief with:

• Goal: what the agent should achieve (one sentence).
• Files: which files/modules are involved.
• Constraints: what the agent must or must not do.
• Done criteria: how to verify the work is complete.
• Spec reference: the parent spec issue, or the prd/features/<slug>.md it belongs to, if any.
• Behaviours touched: entries from prd/behaviours.md this work affects, by number. None is a valid answer and means no test.

Keep briefs under 200 words. The brief is the contract the agent works against — make it specific enough that the agent can execute without guessing.

Completion

Done when: the issue has exactly one type label, one status label, one priority label, and at least one scope label. If status:ready-for-agent, a brief is attached under 200 words. Checkable: gh issue view <n> --json labels shows exactly one type, one status, one priority, and at least one scope label.