Triage issues

Triage Issues — Categorize, Verify, Then Brief

Part of the SHIP wing (production-code craft). Move an incoming report through a small machine: categorize → verify → agent-ready brief. The one failure this skill exists to prevent: writing a brief (or "fixing" anything) straight from the reporter's words, before you have confirmed the claim is even real. The label is ceremony; the verified state is the value.

When to use / when NOT to use

• Use to sort incoming work against something that already exists — a client backlog, beta-tester messages, a pile of "can you also…" asks, a repo's issues, an external PR.
• NOT the bug hunt. Triage does one lightweight repro to confirm a bug is real and scope it; the full reproduce → minimize → hypothesize → instrument → fix loop is diagnose-bugs, handed the brief this skill writes.
• NOT a PR's code review. Triage confirms the diff does what it claims and writes what's left to do; the two-axis (standards + spec) review is review-shipped-code.
• NOT framing a new problem. A vague issue that is really an unstated new project ("we should build a loyalty thing") is not triage — kick it to write-problem-statement, the project entry gate.

Two paths — mode-switchable

Pick the path, state which you took. The state machine is identical; only the ceremony differs.

• Solo list (default): a short backlog with no tracker — client texts, beta feedback, a notes file. No labels, no posted comments, no .out-of-scope/ dir. The states are a status you hold in the list; the deliverable is a brief you hand yourself or an AFK agent. This is the default because he mostly works solo/freelance.
• Tracker + team (mode-switch UP — only when he explicitly has one): a shared GitHub repo where others read the issues. Then the ceremony earns its keep: canonical states map to real label strings, discovery filters external PRs, rejected enhancements get an .out-of-scope/*.md dedup record, and every posted comment opens with > *Generated by AI during triage.* so a human reader knows its provenance.

Recommended default: solo list. Do not stand up tracker ceremony for five WhatsApp messages. Escalate only when the backlog lives in a tracker other people act on.

The one law

No brief before verify. A brief is a contract an AFK agent builds from — writing one from an unverified claim means an agent burns a session on a bug that never reproduced, or on the wrong bug hiding under the reporter's framing. "It reproduces" is a claim about reality → it obeys craft-critique's evidence discipline: you assert it only after you have run the repro (or checked out the PR and run its tests) and watched the exact symptom appear. A confirmed verification also makes a far stronger brief — you can name the real code path, not the reporter's guess.

Intake gate — ask only the gaps

Split what only the reporter knows from what you can find yourself. Ask the first kind once, batched, each with a recommended default; go get the second kind — never ask.

Need	Only the reporter knows → ask (with a default)	Discover yourself — do NOT ask
Exact symptom	"What did you see — the precise error text / wrong result?"	Partly: logs, console, error monitor
Surface + steps	"Which screen, and what did you tap? (default: the confirm step)"	Try the obvious path yourself
What they actually wanted (enhancement)	"What outcome were you after?" — strip any solution they proposed	—
Already built?	—	Search the codebase by concept, not their wording; report where you looked
Already rejected?	—	Check prior decisions / .out-of-scope/ for a matching concept

If every gap has a safe default, state the defaults and proceed — don't stall. A too-vague report where even the default won't do is itself the finding: it goes to needs-info, not to a guessed brief.

The state machine + pick-your-move (situational menu)

Every triaged item carries one category and one state. This is a menu, not a march — the request picks the move; one recommended default.

Category (what is it): bug (something is broken) · enhancement (new/changed behavior).

State (what happens next):

State	Meaning	Move
untriaged	not yet looked at	run the pipeline below
needs-info	can't verify — reporter must answer	post/send the needs-info note (specific questions, not "please clarify")
ready-for-agent	verified + scoped; an AFK agent can build it	write the agent brief ↓
ready-for-human	needs your judgment, external access, or manual testing	write the same brief + note why it can't be delegated
wontfix	won't act	if already built → point to where it lives (do NOT record as a rejection); if rejected → record the reasoning (below)

The three moves, by request:

1. "What needs my attention?" → bucket the backlog oldest-first (untriaged · needs-info with a new reply), one-line each, let him pick. Don't triage the whole pile — surface and wait.
2. "Triage this one" → the default: run categorize → verify → brief on the single item blocking a real user. (Recommended default when unsure which item.)
3. "Just move #X to ready-for-agent" → trust him: confirm the state change (role + any comment), skip the grilling. Then ask whether to write the agent brief now — a forced move may not want the full spec yet, so don't assume it.

The pipeline (for move 2)

1. Gather + categorize. Read the whole item (and prior triage notes — don't re-ask resolved questions). Recommend a category + state with one-line reasoning. Run the two discoverable checks from the intake gate: already built? (concept search → wontfix, point to it) and already rejected? (surface the prior decision, ask if it still stands).
2. Verify the claim (the one law). For a bug: reproduce from the steps; report confirmed (with the code path), failed, or insufficient (→ needs-info). For an enhancement: confirm it isn't already built and isn't a new-problem-in-disguise. For a PR: check it out, run the tests/commands, confirm the diff does what it claims. Guard against the reporter's framing as an anchor — "everything is broken" that can't survive a repro is noise; name-and-control-bias names the anchor, the repro is the control.
3. Grill only if underspecified. If verify shows the request is real but fuzzy, sharpen it one question at a time — the grilling stress-test lives in craft-critique; don't restate it, load it.
4. Apply the outcome per the state table. Write briefs for ready-for-agent / ready-for-human; record rejections (below); send needs-info notes for the rest.

Write the agent-ready brief (Output format)

The deliverable. It shares handoff-context's discipline — behavioral, not procedural; durable, not path-bound — because an agent picks it up cold, days later, against a moved codebase. Before shipping it, run craft-critique's AI-inflation scan on your own wording — a brief is a spec, not a pitch, so strip the superlatives.

## Agent Brief
**Category:** bug / enhancement
**Summary:** one line — what needs to happen

**Current behavior:** what happens now (for a bug: the *verified* broken path, not the reporter's guess)
**Desired behavior:** what should happen after — name the edge/error cases

**Key interfaces:** name the types / function signatures / config shapes to look for or change
  — describe the seam, NOT file paths or line numbers (they go stale)

**Acceptance criteria:**
- [ ] specific, independently testable criterion
- [ ] …

**Out of scope:** what NOT to touch — the adjacent thing that looks related but isn't

Rules that make it durable: describe interfaces + behavioral contracts, never file paths or line numbers; every criterion independently verifiable ("a concurrent-booking test passes", not "booking works"); an explicit out-of-scope so the agent doesn't gold-plate. For ready-for-human, add one line on why it can't be delegated (judgment call, external access, manual device test). For a PR, "Current behavior" describes the diff's state and the brief asks the agent to finish/fix it, not build from scratch.

Recording a rejection (dedup): solo → a one-line note in the workpack's decisions/ (durable ones use write-decision-rationale) so the same ask isn't re-litigated. Tracker mode only → an .out-of-scope/<concept>.md file (one per concept, grouping every prior request), checked on future triage. Never record an already-built feature as a rejection — that poisons the dedup with a false negative.

Worked example — a vague bug report → a scoped brief (catches the failure)

Incoming (a booking app's beta tester, a text message in a short backlog — solo, no tracker): "The app is broken, I can't book anything, it just shows an error."

The anchor to reject: writing the brief straight from this — "Fix the booking error." That is the bad brief: no category that survives scrutiny, no verified path, nothing an agent can test against. Under the one law, it does not get written before verify.

Intake gate. Ask the one thing only she knows, with a default: "Which screen, and what did the error say? (default: the confirm step.)" → "when I hit Confirm." Discover the rest: try the booking path myself; git log shows a slot-availability change deployed yesterday (found, not asked).

Verify (the law in action). Reproduce: booking a free slot works. It only errors when the chosen slot gets taken by someone else between selection and confirm — the server throws a raw 500 instead of "that slot's gone." Verifying changed the whole thing: not "booking is broken" (the anchor, now dead — name-and-control-bias's control did its job) but a specific unhandled taken-slot race. Category confirmed bug, state ready-for-agent.

Brief (behavioral, durable — handed to diagnose-bugs to actually fix):

## Agent Brief
**Category:** bug
**Summary:** A slot taken between selection and confirm throws a raw 500 instead of a recoverable state

**Current behavior:** Verified — when the selected slot is booked by another user before Confirm,
the confirm call fails with an unhandled 500 and a generic error screen. Dead end for the user.
**Desired behavior:** The confirm path detects the now-unavailable slot and returns a recoverable
state — "That slot was just taken, pick another" — dropping the user back into slot selection with
their other choices intact. No raw 5xx reaches the UI.

**Key interfaces:** the availability-check seam invoked on confirm — it should distinguish
"slot taken" from a true server error and surface a typed, recoverable result the UI can branch on.

**Acceptance criteria:**
- [ ] A test simulating a concurrent booking of the same slot returns the recoverable state, not a 500
- [ ] The user can pick another slot without re-entering their details
- [ ] A genuine server error still surfaces as a distinct error state
- [ ] No raw 5xx reaches the booking UI

**Out of scope:** redesigning the slot picker; adding real-time availability push; the confirmation copy polish

What triage caught: it refused to brief "fix the booking error" before reproducing; the repro killed the reporter's framing and produced a testable scope; the brief is behavioral (names the availability seam, not a file) so it survives the codebase moving. The actual red-then-green fix is now diagnose-bugs' job — triage did the sorting and the spec.

Anti-patterns / red flags

Don't	Do
Write a brief from the reporter's words	Verify the claim first — no brief before verify
Trust "everything is broken"	Treat the framing as an anchor; reproduce to find the real path (name-and-control-bias)
Reference file paths / line numbers in a brief	Describe interfaces + behavioral contracts (they survive a refactor)
End a criterion on "booking works"	Make each one independently testable ("a concurrent-booking test passes")
Skip the out-of-scope line	State what NOT to touch so the agent doesn't gold-plate
Stand up tracker labels + disclaimers for 5 texts	Solo list by default; escalate ceremony only for a shared tracker
Record an already-built feature as a rejection	Point to where it lives; only rejected asks get a dedup record
Let one item carry two conflicting states	One category + one state; flag the conflict and ask before acting
Run the full bug hunt inside triage	One lightweight repro to scope it; hand the brief to diagnose-bugs

Boundaries

• diagnose-bugs owns the hunt (reproduce → minimize → hypothesize → fix → regress). Triage does one repro to verify + scope, then hands off the brief. If you're building a red-capable feedback loop, you've left triage.
• review-shipped-code owns a PR's two-axis code review. Triage confirms the diff claims what it does and writes what's left; the standards/spec review is there.
• write-problem-statement owns framing a new problem. A vague ask that's really an unstated project is not triage — route it there.
• craft-critique owns the evidence protocol behind "it reproduces", the grilling stress-test for underspecified asks, and the AI-inflation scan you run on the brief's wording. Load it; never restate it.
• name-and-control-bias owns the named biases triage controls for — anchoring on the reporter's framing, confirmation. The repro is the control.
• design-taste owns what "broken" means for a visual bug (breathing room, one dominant element, the locked motion curves). Load it before you judge a UI report against intent; never eyeball taste from memory.
• handoff-context owns agent→agent session continuation; the agent brief shares its durable/behavioral discipline but is a forward spec for building, not a session state dump.
• write-decision-rationale owns the durable rejection record a solo triage links instead of standing up an .out-of-scope/ KB.

Sources

• Forked from triage — mattpocock/skills, MIT (© Matt Pocock), "Skills For Real Engineers." Kept: the category (bug/enhancement) + state machine, the verify-before-you-brief step, the show-what-needs-attention buckets, the needs-info template idea, and the AGENT-BRIEF discipline (durable over precise, behavioral not procedural, complete testable acceptance criteria, explicit scope). Personalized: solo local-list is the default, with the GitHub tracker / label-mapping / external-PR discovery / AI-disclaimer comment / .out-of-scope/ KB all demoted to a mode-switch-up he takes only when a shared tracker exists; the brief template inlined; cross-linked to diagnose-bugs, review-shipped-code, craft-critique, name-and-control-bias, design-taste, write-problem-statement, and write-decision-rationale.
• AGENT-BRIEF.md and OUT-OF-SCOPE.md in the Pocock source — the brief-writing and dedup-KB references this skill compresses inline.