git:20260809.23ec695 to git:20260818.00f1f2e

---

name: triage

description: Move markdown issues and external-PR requests through triage roles — categorise, verify, grill if needed, and write agent-ready briefs.

disable-model-invocation: true

---

# Triage

External pull requests can still be a request surface: **a PR is input that produces a markdown triage file** under `.scratch/` (same roles, same states, same machine, with a few deltas marked "for a PR" below). Notes, briefs, and state live in that file — never on the PR host as the system of record.

Every triage note appended to a markdown file **must** start with this disclaimer:

```

> *This was generated by AI during triage.*

```

## Reference docs

- [AGENT-BRIEF.md](AGENT-BRIEF.md) — how to write durable agent briefs

- [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md) — how the `.out-of-scope/` knowledge base works

## Roles

Two **category** roles (recorded near the top of the file, e.g. `**Category:** bug`):

- `bug` — something is broken

- `enhancement` — new feature or improvement

Five **state** roles (recorded as `**Status:** <role>`):

- `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

For a PR-originated file, the same states read against the attached code: `ready-for-agent` means a brief is attached and an agent should take the next step on the diff; `ready-for-human` means it's ready for a human to merge.

Every triaged file should carry exactly one category and one status. If statuses conflict, flag it and ask the maintainer before doing anything else.

State transitions: a file with no `**Status:**` normally goes to `needs-triage` first; from there it moves to `needs-info`, `ready-for-agent`, `ready-for-human`, or `wontfix`. `needs-info` returns to `needs-triage` once the reporter replies. The maintainer can override at any time — flag transitions that look unusual and ask before proceeding.

## Invocation

The maintainer invokes triage and describes what they want in natural language. Interpret the request and act. Examples:

- "Show me anything that needs my attention"

- "Let's look at payment-refunds" (file name, path, or title)

- "Move payment-refunds to ready-for-agent"

- "What's ready for agents to pick up?"

- "Triage this PR" (creates or updates a markdown file under `.scratch/` from the PR)

## Show what needs attention

1. **No status** — never triaged (`**Status:**` missing).

2. **`needs-triage`** — evaluation in progress.

3. **`needs-info` with reporter activity since the last triage notes** — needs re-evaluation.

When external PRs are in scope, also surface open external PRs that have no matching triage file yet, tagged `[PR]`. Discovery surfaces only *external* PRs — a collaborator's in-flight PR is not triage work. This filter is discovery-only; an explicitly named PR is always triaged regardless of author. Choosing a PR without a file creates one under `.scratch/` and continues triage there.

Show counts and a one-line summary per item. Let the maintainer pick.

## Triage a specific issue or PR

1. **Gather context.** Read the full markdown file (body, comments, status, category, author notes, dates). For a PR-originated request, read the PR diff too and keep the markdown file as the home for notes. Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the project's domain glossary, respecting ADRs in the area. Run two checks against the codebase: (a) **redundancy** — search for an existing implementation of the requested behavior by domain concept (not just the request's wording), and report where you looked. If found, it's an already-implemented `wontfix` (step 5). (b) **prior rejection** — read `.out-of-scope/*.md` and surface any that resembles this request.

2. **Recommend.** Tell the maintainer your category and status recommendation with reasoning, plus a brief codebase summary relevant to the request — including whether it's already implemented. Wait for direction.

3. **Verify the claim.** Before any grilling, check that the claim holds up. For a bug, reproduce it from the reporter's steps. For a PR, confirm the diff does what it claims — check it out, run the relevant tests or commands. Report what happened: confirmed (with code path), failed, or insufficient detail (a strong `needs-info` signal). A confirmed verification makes a much stronger agent brief.

4. **Grill (if needed).** If the request needs fleshing out, run the `grilling` and `domain-modeling` skills together — grill it into shape one question at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land.

5. **Apply the outcome** by editing the markdown file:

- `ready-for-agent` — set `**Status:** ready-for-agent` and append an agent brief ([AGENT-BRIEF.md](AGENT-BRIEF.md)).

- `ready-for-human` — set status; same structure as an agent brief, but note why it can't be delegated (judgment calls, external access, design decisions, manual testing).

- `needs-info` — set status and append triage notes (template below).

- `wontfix` — set status and close out, with the note depending on *why*:

- **Already implemented** — the change already exists in the codebase. Point to where it lives; do **not** write to `.out-of-scope/` (that KB is for *rejected* requests, not built ones).

- **Rejected (bug)** — polite explanation, then done.

- **Rejected (enhancement)** — write to `.out-of-scope/`, link to it from a note in the file ([OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)).

- `needs-triage` — set the status. Optional note if there's partial progress.

## Quick state override

If the maintainer says "move payment-refunds to ready-for-agent", trust them and apply the status directly. Confirm what you're about to do (status change, notes, brief), then act. Skip grilling. If moving to `ready-for-agent` without a grilling session, ask whether they want to write an agent brief.

## Needs-info template

```markdown

## Triage Notes

**What we've established so far:**

- point 1

- point 2

**What we still need from you (@reporter):**

- question 1

- question 2

```

Capture everything resolved during grilling under "established so far" so the work isn't lost. Questions must be specific and actionable, not "please provide more info".

## Resuming a previous session

If prior triage notes exist on the file, read them, check whether the reporter has answered any outstanding questions, and present an updated picture before continuing. Don't re-ask resolved questions.