triage

Triage

Move tasks on the configured tracker through a small state machine of intake roles. Triage acts on remote records or local intake task bodies; unresolved proposals in a capability's draft have no role.

If the tracker treats external pull requests as a request surface, triage covers them too. A PR is a task with attached code, using the same roles and states, with the differences noted below. Resolve a bare #42 to an issue or PR through the tracker configuration.

Document and tracker contract

The project documents and their rules are in project-documents.md; read it before updating project documents. Its terms (authorized, obligation, lazy, pointer) apply throughout. Read the relevant requirements, specifications, working state, and backlog when present.

Read the task tracker configuration and the triage roles that AGENTS.md points to. When the tracker configuration is missing, ask the user where the tasks live for this run (the repository remote's issue tracker through its command-line tool or a connected server, or local intake task bodies) and verify read access with one read-only query before triaging. When the roles are missing, use the canonical strings below. Say in the report which configuration was missing and what this run assumed; record nothing as configuration.

"Comment", "apply a role", and "close" resolve through the tracker configuration:

• Remote operations use the platform's actual commands and labels. A local title/link reference to a published remote task does not duplicate remote role state.
• Local task bodies use Category: and Status: near the top. Comments append under ## Comments. Rejection closes intake with Status: not-planned. Delivery progress, blockers, and acceptance evidence can be recorded in the body separately from intake state.

Remote comments, role changes, and closing need authorization from the maintainer's explicit triage request or confirmed outcome. A generic local document edit grants no remote publication authority. Maintain specifications, active work, and the changelog locally within scope. Candidate deferrals follow the backlog authority in project-documents.md; do not create a local queue beside a remote backlog.

Every comment or new task posted during triage starts with:

> *This was generated by AI during triage.*

Reference documents

• agent-brief.md: durable ready briefs.
• out-of-scope.md: the rejected-enhancement knowledge base.

Roles

Category roles:

• bug: something is broken.
• enhancement: new feature or improvement.

Intake-state roles:

• to-evaluate: maintainer needs to evaluate.
• on-hold: paused on a named reply, dependency, or blocker.
• ready: fully specified, with a brief attached, safe to pick up.
• not-planned: closed without action, reason recorded.

These states answer whether work is actionable. In-progress, review, and deployed state belong to the tracker's own delivery fields, local task progress, a branch, or a PR.

A ready brief can identify work a human must implement and the reason it cannot be delegated, such as access, judgment, or manual testing. This is a line in the brief, not another role. For a PR, ready means the next step on its diff is specified, whether an agent finishes it or a human merges it.

Each triaged task carries exactly one category and one state. If states conflict (two state lines on one task, or a role that disagrees with the tracker's own state), show each with its source and date, recommend the one the latest evidence supports (the newest comment, the linked pull request's status), and apply no role until the maintainer picks. The role file maps canonical roles to the project's actual strings; use that mapping instead of creating duplicate vocabulary.

Normally, an untriaged task enters to-evaluate, then moves to on-hold, ready, or not-planned. A hold returns to to-evaluate when its named condition arrives. The maintainer can override; flag unusual transitions and confirm them first.

Invocation

The maintainer runs /triage and describes the request:

• "Show me anything that needs my attention."
• "Let's look at #42."
• "Move #42 to ready."
• "What's ready for agents to pick up?"

Show what needs attention

Query the configured tracker and show three buckets, oldest first:

1. Untriaged tasks, with no state role.
2. to-evaluate tasks.
3. on-hold tasks whose named condition has arrived. Check notes for the reply, merged dependency, or closed blocker before surfacing them.

When PRs are in scope, tag entries [PR] or [task]. Discovery includes external PRs only, using the configuration's author filter; an explicitly named PR is triaged regardless of author. Show counts and a one-line summary per item, then let the maintainer choose.

Triage a task or PR

1. Gather context. Read body, comments, roles, author, dates, and prior triage notes; for a PR, also read the diff. Explore with the domain glossary and applicable architecture decision records that AGENTS.md points to. Search for an existing implementation by domain concept and report where you looked. Read the records in the out-of-scope folder AGENTS.md names, when it names one, and surface matching prior rejections.
2. Recommend. Present a category and state with reasoning and a relevant codebase summary, including any already-implemented behavior. Wait for direction.
3. Verify. Before refinement, reproduce a bug from the reporter's steps. For a PR, check the diff against its claims and run relevant tests or commands. Report confirmed behavior with its code path, failure, or insufficient detail. Insufficient detail supports an on-hold recommendation.
4. Refine if needed. Resolve questions with the human following the interview method. When a term is fuzzy, disputed, or clashes with the glossary or the code, name the conflict, test it with a concrete scenario, recommend a canonical term, and once the human agrees, write it to the glossary following glossary-format.md. Keep unresolved proposals in the capability's draft, incorporate agreed behavior and acceptance into its specifications, and record a hard-to-reverse decision following decision-record-format.md.
5. Apply the confirmed outcome:
   • ready: post an agent brief. It is the authoritative task-execution contract, linked to canonical specifications and applicable requirements. State any reason the work needs a human.
   • on-hold: post notes naming exactly what the hold waits on. Keep candidate deferrals in the authoritative configured backlog: local bodies for local tracking, approved remote updates for remote tracking. Pending publication and active paused work belong in local working state, not in a competing backlog or copied tracker status.
   • not-planned, already implemented: close with a link to the existing implementation. This is not a rejection and does not enter the rejection knowledge base.
   • not-planned, rejected bug: explain politely and close.
   • not-planned, rejected enhancement: create or update the out-of-scope record, link it in a comment, then close.
   • to-evaluate: apply the role and optionally record partial progress.
6. Update relevant local context and the root changelog following project-documents.md. Report the outcome and any next action.

Quick state override

If the maintainer requests a state directly, trust their decision. Confirm the role changes, comment, or closing before acting, and skip refinement. If moving to ready without a refinement session, ask whether they want an agent brief. This explicit override does not pretend a missing brief exists.

On-hold template

## Triage Notes

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

- Resolved fact or decision

**Waiting on:** the concrete reply, dependency, or blocker that must arrive

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

- Specific, actionable question

Capture resolved questions so later sessions do not repeat them. Name the hold precisely enough to check whether it has lifted without rereading the whole thread.

Resuming

Read prior notes, outstanding answers, and relevant active-work context. Check whether the named hold has lifted and present an updated picture before continuing. Reuse resolved answers instead of asking again.