triage

Triage

Move issues on tracker through small state machine of triage roles.

When explore codebase, use project domain glossary so titles, comments, agent briefs match project language. Respect ADRs in area touched.

AI Disclaimer

Every comment posted to tracker during triage must start with:

> *This was generated by AI during triage.*

Issue Tracker

Detect by git remote -v + repo conventions:

• GitHub (github.com remote) -> use gh
• Jira (Atlassian-style ticket IDs in branches/commits, or .atlassian/ config) -> use acli

Both present (GitHub repo + Jira tickets) -> ask which user want file/triage against.

Roles

Two category roles:

• bug -- something broken
• enhancement -- new feature or improvement

Five state roles:

• needs-triage -- maintainer must evaluate
• needs-info -- wait on reporter for more info
• ready-for-agent -- fully specified, ready for AFK agent
• ready-for-human -- need human implementation
• wontfix -- will not action

Every triaged issue carry exactly one category role + one state role. Conflicting states -> flag and ask before act.

Canonical role names. Actual label/status strings in tracker may differ -- when differ, infer from existing labels/statuses on project, ask once, remember within session.

Reference docs

• tracker-github.md -- GitHub commands via gh
• tracker-jira.md -- Jira commands via acli
• AGENT-BRIEF.md -- how write durable agent briefs
• OUT-OF-SCOPE.md -- the .out-of-scope/ knowledge base
• REFERENCE.md -- needs-info template, full triage workflow, TDD-fix-plan mode

Invocation

User invoke /triage and describe want in natural language. Examples:

• "Show me anything that needs my attention"
• "Let's look at #42" / "Let's look at FOO-123"
• "Move #42 to ready-for-agent"
• "What's ready for agents to pick up?"
• "Users report the sidebar flickers on navigation" -> bug investigation -> file ticket

Interpret and act.

Show what needs attention

Query tracker. Present three buckets, oldest first:

1. Unlabeled / no-status -- never triaged
2. needs-triage -- evaluation in progress
3. needs-info with reporter activity since last triage notes -- need re-evaluation

Show counts + one-line summary per issue. Let maintainer pick.

Triage a specific issue

1. Gather context. Read full issue (body, comments, labels/status, reporter, dates). Parse prior triage notes so resolved questions not re-asked. Explore codebase using project domain glossary, respect ADRs in area. Read .out-of-scope/*.md -- surface any prior rejection resembling issue.

2. Recommend. Tell maintainer category + state recommendation with reasoning, plus brief codebase summary relevant to issue. Wait for direction.

3. Reproduce (bugs only). Before grill, attempt repro: read reporter steps, trace code, run tests or commands. Report what happened -- successful repro with code path, failed repro, or insufficient detail (strong needs-info signal). Confirmed repro make much stronger agent brief. For root-cause investigation + TDD fix plan, see REFERENCE.md#tdd-fix-plan-mode.

4. Grill (if needed). Issue need flesh out -> run /grill-me for a fast grill or /grill-with-docs when domain language/ADRs matter.

5. Apply the outcome:

   • ready-for-agent -> post agent brief comment (AGENT-BRIEF.md)
   • ready-for-human -> same structure, but note why can't delegate
   • needs-info -> post triage notes (see REFERENCE.md)
   • wontfix (bug) -> polite explanation, then close
   • wontfix (enhancement) -> write to .out-of-scope/, link from comment, then close (OUT-OF-SCOPE.md)
   • needs-triage -> apply role; optional comment if partial progress

Quick state override

User say "move #42 to ready-for-agent" -> trust them, confirm what about to do (role changes, comment, close), then act. Skip grill. If move to ready-for-agent without grill session, ask whether want agent brief written.

Resuming a previous session

Prior triage notes exist on issue -> read them, check whether reporter answered outstanding questions, present updated picture before continue. Don't re-ask resolved questions.

State Machine

Full transition table: REFERENCE.md#state-machine.