triage

Files (1)

• SKILL.md

SKILL.md (first lines)

# Triage

Move issues through a small state machine of triage roles.

Every comment or issue posted during triage must start with:

```
> *This was generated by AI during triage.*
```

Assumes your repo has a `CONTEXT.md` (domain glossary) and `docs/adr/` (decisions recorded). If not, run `/setup-mateonunez-skills` first. Issue tracker and triage label vocabulary come from setup.

## Roles

**Two category roles:**
- `bug` — something is broken
- `enhancement` — new feature or improvement

**Five state roles:**
- `needs-triage` — you need 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 carries exactly one category role and one state role. If state roles conflict, flag it and ask before proceeding.

State transitions: 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 reporter replies. You can override any time — flag unusual transitions and ask before acting.

## Invocation

Describe what you want in natural language. I interpret and act. Examples:

- "Show me anything that needs your 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 one-line summary per issue. Let user 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 domain glossary, respecting ADRs in the area. Surface any prior rejection resembling this issue.

2. **Recommend.** Tell the user your category and state recommendation with reasoning, plus brief codebase summary relevant to the issue. Wait for direction.

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

4. **Grill (if needed).** If the issue needs fleshing out, run a grilling session.

5. **Apply the outcome:**
   - `ready-for-agent` — post an agent brief comment
   - `ready-for-human` — same structure as 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 from comment, then close
   - `needs-triage` — apply the role. Optional comment if there's partial progress.

## Quick state override

If user 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 grilling, 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 answered any outstanding questions, and present an updated picture before continuing. Don't re-ask resolved questions.

From mateonunez/skills, MIT.

More from mateonunez/skills