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.