221ffca967
- Introduced a human-in-the-loop script for bug diagnosis to capture user feedback. - Created ADR and CONTEXT formats to standardize architectural decision records and domain context documentation. - Developed a domain modeling skill to refine terminology and maintain a shared language. - Enhanced the improve-codebase-architecture skill to provide visual reports and deepening opportunities. - Consolidated grilling and handoff skills for better user interaction and documentation. - Updated existing skills to improve clarity and consistency in descriptions and functionality.
104 lines
4.9 KiB
Markdown
104 lines
4.9 KiB
Markdown
---
|
|
name: triage
|
|
description: Move issues through a state machine of triage roles — categorise, reproduce, grill if needed, and write agent-ready briefs.
|
|
disable-model-invocation: true
|
|
---
|
|
|
|
# Triage
|
|
|
|
Move issues on the project issue tracker through a small state machine of triage roles.
|
|
|
|
Every comment or issue posted to the issue tracker during triage **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:
|
|
|
|
- `bug` — something is broken
|
|
- `enhancement` — new feature or improvement
|
|
|
|
Five **state** roles:
|
|
|
|
- `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
|
|
|
|
Every triaged issue should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else.
|
|
|
|
These are canonical role names — the actual label strings used in the issue tracker may differ. The mapping should have been provided to you - run `/setup-matt-pocock-skills` if not.
|
|
|
|
State transitions: an unlabeled issue 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 #42"
|
|
- "Move #42 to ready-for-agent"
|
|
- "What's ready for agents to pick up?"
|
|
|
|
## Show what needs attention
|
|
|
|
Query the issue tracker and present three buckets, oldest first:
|
|
|
|
1. **Unlabeled** — never triaged.
|
|
2. **`needs-triage`** — evaluation in progress.
|
|
3. **`needs-info` with reporter activity since the last triage notes** — needs re-evaluation.
|
|
|
|
Show counts and a one-line summary per issue. Let the maintainer pick.
|
|
|
|
## Triage a specific issue
|
|
|
|
1. **Gather context.** Read the full issue (body, comments, labels, reporter, dates). 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. Read `.out-of-scope/*.md` and surface any prior rejection that resembles this issue.
|
|
|
|
2. **Recommend.** Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary relevant to the issue. 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. Report 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. **Grill (if needed).** If the issue needs fleshing out, run the `/grilling` and `/domain-modeling` skills together — grill the issue into shape one question at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land.
|
|
|
|
5. **Apply the outcome:**
|
|
- `ready-for-agent` — post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)).
|
|
- `ready-for-human` — same structure as an agent brief, but note why it can't be delegated (judgment calls, external access, design decisions, manual testing).
|
|
- `needs-info` — post triage notes (template below).
|
|
- `wontfix` (bug) — polite explanation, then close.
|
|
- `wontfix` (enhancement) — write to `.out-of-scope/`, link to it from a comment, then close ([OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)).
|
|
- `needs-triage` — apply the role. Optional comment if there's partial progress.
|
|
|
|
## Quick state override
|
|
|
|
If the maintainer says "move #42 to ready-for-agent", trust them and apply the role directly. Confirm what you're about to do (role changes, comment, close), 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 issue, read them, check whether the reporter has answered any outstanding questions, and present an updated picture before continuing. Don't re-ask resolved questions.
|