triage

Triage

Move issues through a small state machine on the repo's configured tracker. Read the tracker operations from docs/agents/issue-tracker.md and the label strings from docs/agents/triage-labels.md; if either is missing, say so and suggest configure-repo before continuing (you can still triage read-only in the meantime).

If the tracker config says external pull requests are a request surface, they go through the same machine — a PR is an issue with attached code. Collaborators' in-flight PRs are not triage work; an explicitly named PR is always in scope.

Every comment you post to the tracker starts with this exact line:

> *This was generated by AI during triage.*

Supporting reference: agent-brief-template.md — the brief format and its durability rules.

The state machine

Two axes; every triaged issue carries exactly one label from each:

• Category: bug (broken behavior) or enhancement (new capability)
• State: needs-triage → one of needs-info / shaping / ready-for-agent / ready-for-human / wontfix

needs-info returns to needs-triage when the reporter replies. These are canonical role names — apply the repo's mapped label strings, never the raw role names, unless they coincide. If an issue carries conflicting state labels, flag it and ask the user before touching it.

Scope rule

Only triage issues the user did not produce through this skill set's own planning. Issues born agent-ready are recognizable by a marker in the body — a Requirements covered: section (published by plan-tasks) or a marker line beginning > *This issue was drafted by AI with (published by publish-issues). Running either through triage adds a second, weaker spec on top of a real one. Skip them and say why.

Showing the queue

When asked "what needs attention", query the tracker and present three buckets, oldest first, with counts and a one-line summary per item: (1) unlabeled, (2) needs-triage, (3) needs-info with reporter activity since the last triage notes. Tag lines [issue]/[PR] when PRs are in scope. Let the user pick.

Triaging one issue

1. Gather context. Read the full issue — body, comments, labels, author, dates; for a PR, the diff. Read any prior triage notes so you never re-ask an answered question. Explore the relevant code using the glossary in CONTEXT.md. When docs/architecture/ exists and the issue touches a spine it covers, REQUIRED SUB-SKILL: use inspect-invariants for the conformance read rather than judging it here. Then run two checks:

   • Redundancy: search the codebase for an existing implementation of the requested behavior — search by domain concept, not the reporter's wording. If it already exists, the outcome is an already-implemented close (step 5); collect the evidence (where it lives, how to invoke it). If nothing matches, write down the concepts you searched.
   • Prior rejection: read .out-of-scope/*.md and surface any concept that resembles this request — match by idea, not keyword. If one matches, tell the user what was rejected before and why, and ask whether the decision stands. If none matches, write that down too.

   Done when: both checks have a written result — the redundancy search naming either the existing implementation or the concepts searched, and the prior-rejection read naming either the matching record or that none matched.

2. Verify the claim. Before recommending anything, test whether the claim holds. For a bug: reproduce it from the reporter's steps. For a PR: check out the diff and run the relevant tests or commands to confirm it does what it says. Report one of: confirmed (with the code path), could not reproduce, or insufficient detail — the last is a strong needs-info signal. Done when: you have first-hand evidence, not just the reporter's word.

3. Recommend. Tell the user your category + state recommendation with the reasoning and the evidence from steps 1–2. If the request is ambiguous or underspecified in ways only the user can resolve — REQUIRED SUB-SKILL: use clarify-decisions to shape it one question at a time before locking the recommendation. Wait for the user's direction.

4. Apply the outcome:

   • shaping — a confirmed bug whose root cause is not yet established, so the brief would send an agent to investigate. Post the agent brief with the cause marked open, and name /shape #N, which runs root-cause and writes the tier-1 mini-spec the build needs. In three of four baseline triages of klynt #242, the brief itself said "requires a root-cause investigation before the fix" and the recommendation was still ready-for-agent. /go and /board count a ticket as Ready only once its spec is approved, so #242 sat in Ready with nothing able to build it.
   • ready-for-agent — post an agent brief built from agent-brief-template.md. The brief is the contract; the original body and thread are only context.
   • ready-for-human — same brief structure, plus one line on why it cannot be delegated (judgment call, external access, design decision, manual testing).
   • needs-info — post triage notes: what has been established so far, then specific, answerable questions for the reporter (never "please provide more info").
   • wontfix — close, and the comment depends on why:
     • Already implemented: point to where the behavior lives, with the evidence from step 1. Do not write to .out-of-scope/ — that KB records rejections, and logging built features there poisons future dedup checks.
     • Rejected bug: polite explanation, close.
     • Rejected enhancement: write or update the concept's file in .out-of-scope/ (rules below), link it from the closing comment, close.
   • staying needs-triage — apply the label; comment only if there is partial progress worth recording.

   Done when: the issue carries exactly one category and one state label and any required comment is posted.

The .out-of-scope/ knowledge base

One file per concept, kebab-case (plugin-system.md), never one per issue — repeat requests append to the existing file's prior-request list. Each file carries: a heading naming the concept, the decision, a durable reason (project scope, architectural constraint, deliberate trade-off — never "no time right now", which is a deferral, not a rejection), and a Prior requests list linking every issue that asked. Written in plain prose a future maintainer can act on. If the user reverses a past rejection, delete or rewrite the file and triage the new issue normally.

Direct state changes

When the user names an issue and its target state ("move #42 to ready-for-agent"), that is a decision, not a triage request — it skips the investigate/prove-claim/recommend pipeline (steps 1–3), but not the guardrails:

1. State back exactly what the change is — the label edits, any comment, whether it closes — and get the user's go-ahead before touching the tracker.
2. For a jump straight to ready-for-agent, offer to write the brief from agent-brief-template.md; an unbriefed agent-ready issue is a trap for the next agent.