triage

name	triage
description	Triage vault research artifacts and tasks with category and stage metadata. Use when the user asks to classify, prioritize, tag, or prepare vault work for agents or humans.
user-invocable	true

Triage

Move blueprints vault artifacts through a small state machine of triage roles.

The blueprints vault is canonical. Use vault_* tools when available; fall back to vlt only when no tool covers the operation.

Every triage note, agent brief, or decision note written to a vault artifact must start with this disclaimer:

> *This was generated by AI during triage.*

Roles

Two category tags:

• category/bug — something is broken
• category/enhancement — new feature or improvement

Five state tags:

• stage/needs-triage — maintainer needs to evaluate
• stage/needs-info — waiting on reporter for more information
• stage/ready-for-agent — fully specified, ready for an AFK agent
• stage/ready-for-human — needs human implementation
• stage/wontfix — will not be actioned

Every triaged artifact should carry exactly one category tag and one state tag. If state tags conflict, flag it and ask the maintainer before doing anything else. To change state, edit the artifact frontmatter tags and commit through the vault workflow.

State transitions: an untriaged artifact normally gets stage/needs-triage first; from there it moves to stage/needs-info, stage/ready-for-agent, stage/ready-for-human, or stage/wontfix. stage/needs-info returns to stage/needs-triage once the reporter answers in the artifact or conversation. 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 the quote-cache PRD"
• "Move the quote-cache plan to ready-for-agent"
• "What's ready for agents to pick up?"

Show what needs attention

Query the vault and present three buckets, oldest first:

1. No stage tag — never triaged.
2. stage/needs-triage — evaluation in progress.
3. stage/needs-info with newer artifact edits or user-provided answers since the last triage notes — needs re-evaluation.

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

Triage a specific artifact

1. Gather context. Read the full vault artifact body, frontmatter tags, related artifacts, and prior triage notes so you don't re-ask resolved questions. Search/read relevant vault domain and decision artifacts, then explore the codebase. Search the vault for stage/wontfix out-of-scope docs and surface any prior rejection that resembles this request.

2. Recommend. Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary relevant to the artifact. Wait for direction.

3. Reproduce (bugs only). Before any grilling, attempt reproduction: read the reporter's steps, trace the relevant code, run tests or commands. State what happened — successful repro with code path, failed repro, or insufficient detail (a strong needs-info signal). A confirmed repro makes a much stronger agent brief.

4. Question (if needed). If the artifact needs fleshing out, run a $question session.

5. Apply the outcome:

   • stage/ready-for-agent — append an agent brief section to the artifact.
   • stage/ready-for-human — append the same structure as an agent brief, but note why it can't be delegated (judgment calls, external access, design decisions, manual testing).
   • stage/needs-info — append triage notes (template below).
   • stage/wontfix (bug) — append a polite explanation and mark the artifact stage/wontfix.
   • stage/wontfix (enhancement) — create or update a vault doc artifact for the out-of-scope concept, tag it stage/wontfix, link it from the triaged artifact, and mark the triaged artifact stage/wontfix.
   • stage/needs-triage — apply the tag. Optional note if there's partial progress.

Quick state override

If the maintainer says "move this to ready-for-agent", trust them and apply the tag directly. Confirm what you're about to do (tag changes and appended notes), then act. Skip grilling. If moving to stage/ready-for-agent without a grilling session, ask whether they want to write an agent brief.

Agent brief template

> *This was generated by AI during triage.*

## Agent Brief

**Category:** bug / enhancement
**Summary:** one-line description of what needs to happen

**Current behavior:**
Describe what happens now. For bugs, this is the broken behavior. For enhancements, this is the status quo the feature builds on.

**Desired behavior:**
Describe what should happen after the agent's work is complete. Be specific about edge cases and error conditions.

**Key interfaces:**
- `TypeName` — what needs to change and why
- `functionName()` return type — what it currently returns vs what it should return
- Config shape — any new configuration options needed

**Acceptance criteria:**
- [ ] Specific, testable criterion 1
- [ ] Specific, testable criterion 2
- [ ] Specific, testable criterion 3

**Out of scope:**
- Thing that should NOT be changed or addressed in this artifact
- Adjacent feature that might seem related but is separate

Write briefs for durability: describe behavior, interfaces, and contracts; avoid line numbers and brittle procedural steps.

Needs-info template

> *This was generated by AI during triage.*

## 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 artifact, read them, check whether the user has answered any outstanding questions, and present an updated picture before continuing. Don't re-ask resolved questions.