triage

Files (5)

• AGENT-BRIEF.md
• BRIEF-AGENTE.md
• FORA-DO-ESCOPO.md
• OUT-OF-SCOPE.md
• SKILL.md

SKILL.md (first lines)

# Triage

Move issues through the project's issue tracker via a small state machine of triage roles.

Every comment or issue posted to the issue tracker during triage **must** begin with this notice:

```
> *This content was AI-generated during triage.*
```

## Reference Documents

- [BRIEF-AGENTE.md](BRIEF-AGENTE.md) — how to write durable agent briefs
- [FORA-DO-ESCOPO.md](FORA-DO-ESCOPO.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 for more information from the reporter
- `ready-for-agent` — fully specified, ready for an AFK agent
- `ready-for-human` — needs human implementation
- `wontfix` — will not be done

Every triaged issue must 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 typically 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` when the reporter responds. 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 everything 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 last triage notes** — needs re-evaluation.

Show counts and a one-line summary per issue. Let the maintainer choose.

## Triage a Specific Issue

1. **Gather context.** Read the full issue (body, comments, labels, reporter, dates). Parse any previous triage notes so you don't re-ask resolved questions. Explore the code 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 rationale, plus a brief summary of the code relevant to the issue. Wait for guidance.

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 reproduction with code path, failed reproduction, or insufficient details (a strong signal for `needs-info`). A confirmed reproduction produces a much stronger agent brief.

4. **Grill (if needed).** If the issue needs further elaboration, run a `/entrevista-com-docs` session.

5. **Apply the outcome:**
   - `ready-for-agent` — post an agent brief comment ([BRIEF-AGENTE.md](BRIEF-AGENTE.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/`, reference in a comment, then close ([FORA-DO-ESCOPO.md](FORA-DO-ESCOPO.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 it and apply the role directly. Confirm what you're about to do (role changes, comment, closure), then act. Skip the grilling. If moving to `ready-for-agent` without a grilling session, ask if they want an agent brief written.

## Needs-Info Template

```markdown
## Triage Notes

**What we've established:**

- point 1
- point 2

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

- question 1
- question 2
```

Capture everything resolved during grilling under "what we've established" so the work isn't lost. Questions should be specific and actionable, not "please provide more information."

## Resume a Previous Session

If previous triage notes exist on the issue, read them, check whether the reporter has answered any outstanding questions, and present an updated picture before continuing. Do not re-ask resolved questions.

From hcb2019/claude-code-skills, MIT.

More from hcb2019/claude-code-skills