# Triage

> Move issues through triage: categorise, assess readiness, assign labels, write briefs.

- Skill: `y3owk1n/triage` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add y3owk1n/triage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/y3owk1n/triage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: y3owk1n (https://skillmd.com/u/y3owk1n)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/y3owk1n/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.