# Triage

> Move issues through a triage state machine: from raw inbox to labeled, scoped, and ready for planning. Define triage roles/labels, apply them consistently, and surface what is ready to become a plan. Use when managing a backlog of issues or tickets before they become plans, or when the user says "triage", "go through issues", "organize the backlog", "what should I work on", "prioritize issues".

- Skill: `arendon1/triage` (Agent Skill)
- Install (CLI): `npx skillmds@latest add arendon1/triage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arendon1/triage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: arendon1 (https://skillmd.com/u/arendon1)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/arendon1/triage

---


# triage — inbox to ordered backlog

Move issues through a triage state machine: from a raw inbox to labeled, scoped,
and ready for planning. Define triage roles/labels, apply them consistently, and
surface what is ready to become a plan.

## OWNERSHIP

Owns: the triaged issue list (in the project's issue tracker, or a local
`BACKLOG.md` if no tracker).
Reads: the issue tracker / inbox, `CONTEXT.md`.
MUST NOT write plan artifacts. A triaged `ready-for-agent` issue becomes a plan
via `grill` — triage stops at "ready".

## WHEN (user-invoked)

- User says "triage", "go through issues", "organize the backlog", "what should I
  work on", "prioritize issues".
- An inbox of unsorted issues/tickets needs categorizing before planning.

## THE STATE MACHINE

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 carries **exactly one** category role and **one** state role.
If state roles conflict, flag it and ask the maintainer before proceeding.

### State transitions

```
unlabeled -> needs-triage
needs-triage -> needs-info | ready-for-agent | ready-for-human | wontfix
needs-info -> needs-triage   (when reporter replies)
```

The maintainer can override at any time. Flag transitions that look unusual and
ask before proceeding.

### Canonical vs actual labels

These are canonical role names. The actual label strings used in the issue tracker
may differ. If the repo has a triage-label mapping, use it. If not, ask the user
to define one (or use the canonical names as the actual labels).

## STEP 0 — CONFIGURE

If the repo has no triage configuration, establish it:
- Category roles + state roles (the canonical set above).
- The label mapping (canonical -> actual tracker labels).
- Where the issue tracker is (or `BACKLOG.md` if none).

Write the config to the repo once (e.g. `TRIAGE.md` or in `CONTEXT.md`). Skip this
on subsequent runs.

## STEP 1 — PULL THE INBOX

Fetch unlabeled / `needs-triage` issues from the tracker (or read `BACKLOG.md`).
For each:
1. Read the issue body + any comments.
2. Categorize: `bug` or `enhancement`.
3. Determine the state:
   - Is it fully specified? -> `ready-for-agent` or `ready-for-human`.
   - Missing information? -> `needs-info` (post a comment asking for specifics).
   - Unclear? -> `needs-triage` (flag for the maintainer).
   - Out of scope / won't be done? -> `wontfix`.

## STEP 2 — GRILL IF NEEDED

If an issue is almost `ready-for-agent` but has fuzz, invoke the `grill` loop on
it (in interview mode with the reporter or maintainer) to sharpen it into a
spec-ready brief. A `ready-for-agent` issue MUST be fully specified — no guessing.

## STEP 3 — WRITE AGENT-READY BRIEFS

For each `ready-for-agent` issue, write a durable brief attached to the issue:
- **What to build** — concise, end-to-end behavior (not layer-by-layer).
- **Acceptance criteria** — observables that prove it's done.
- **Context** — relevant `CONTEXT.md` terms, ADRs, code paths.

A `ready-for-agent` issue is the input to `grill` / `plan` — the next session can
pick it up and run.

## STEP 4 — SURFACE WHAT'S READY

End the triage run with a summary:

```
triage run <date>:
- N issues processed
- ready-for-agent: <list> (these can become plans via grill)
- ready-for-human: <list>
- needs-info: <list> (waiting on reporters)
- needs-triage: <list> (maintainer attention)
- wontfix: <list>
next: grill on <highest-priority ready-for-agent issue>
```

## AI DISCLAIMER

Every comment or issue posted to the tracker during triage MUST start with:

```
> *This was generated by AI during triage.*
```

## BOUNDARIES

- MUST apply exactly one category + one state role per issue.
- MUST flag conflicting state roles and ask the maintainer.
- MUST grill (via the `grill` loop) any issue that is almost ready but fuzzy.
- MUST write a durable brief on every `ready-for-agent` issue.
- MUST NOT turn an issue into a plan — that's `grill`'s job. Stop at `ready`.
- MUST post the AI disclaimer on every tracker comment.
- MUST use `caveman` for the summary and `CONTEXT.md` canonical terms in briefs.