| name | triage |
| description | Move issues through triage: categorise, assess readiness, assign labels, write briefs. |
| disable-model-invocation | true |
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:
- Unlabeled: never triaged.
status:needs-triage: evaluation in progress.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
-
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.
-
Categorise. Assign one type label: type:bug, type:feature, type:spec, type:ticket, type:docs, or type:chore.
-
Assess readiness. Can an agent pick this up as-is? Does it need more info from the reporter? Is it out of scope?
-
Assign status. Move to the appropriate status label. If status:ready-for-agent, write a brief (see below).
-
Assign priority. Ask the user or infer from impact.
-
Assign scope. Which area(s) does this touch?
-
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.
