# Triage

> Moves tracker issues through a structured triage state machine with category and readiness decisions; use to evaluate or prepare work items for implementation.

- Skill: `akillness/triage` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add akillness/triage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/akillness/triage/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML, Product & Planning
- Author: akillness (https://skillmd.com/u/akillness)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/akillness/triage

---


# Triage

Move issues through a structured state machine. Every AI-generated comment **must** start with:

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

## Roles

**Category roles** (one per issue):
- `bug` — something is broken
- `enhancement` — new feature or improvement

**State roles** (one per issue):
- `needs-triage` — needs evaluation
- `needs-info` — waiting on reporter
- `ready-for-agent` — fully specified, AFK-implementable
- `ready-for-human` — needs human (judgment, design, manual testing)
- `wontfix` — will not be actioned

State transitions: `needs-triage` → `needs-info` | `ready-for-agent` | `ready-for-human` | `wontfix`. `needs-info` returns to `needs-triage` when reporter replies.

Label strings in the tracker may differ from these canonical names — run `/setup-matt-pocock-skills` to configure the mapping.

## Invocation

Natural language: "Show me what needs attention", "Let's look at #42", "Move #42 to ready-for-agent", "What's ready for agents?"

## Show what needs attention

Present three buckets (oldest first):
1. **Unlabeled** — never triaged
2. **`needs-triage`** — evaluation in progress
3. **`needs-info` with reporter activity** — needs 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, dates). Check `.out-of-scope/` for prior rejections.

2. **Recommend** — state your category + state recommendation with reasoning. Wait for direction.

3. **Reproduce (bugs only)** — trace the relevant code, run tests. Report: confirmed repro, failed repro, or insufficient detail.

4. **Grill if needed** — run a `grill-with-docs` session to flesh out the issue.

5. **Apply outcome:**
   - `ready-for-agent` → post an agent brief
   - `ready-for-human` → same structure, note why it can't be automated
   - `needs-info` → post triage notes (template below)
   - `wontfix (bug)` → polite explanation, close
   - `wontfix (enhancement)` → write to `.out-of-scope/`, link comment, close

## Quick state override

If maintainer says "move #42 to ready-for-agent" — trust them, apply directly. Confirm changes before acting. Skip grilling. Ask if they want 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 (specific and actionable)
- question 2
```

## Resuming a session

If prior triage notes exist, read them, check if reporter answered questions, present updated picture. Don't re-ask resolved questions.

## When to use this skill
- Use this skill when you need the workflow described above and want consistent, repeatable execution.

## Instructions
1. Identify the task trigger and expected output.
2. Follow the workflow steps in this skill from top to bottom.
3. Validate outputs before moving to the next step.
4. Capture blockers and fallback path if any step fails.

## Examples
- Example: Apply this skill to a small scope first, then scale to full scope after validation passes.

## Best practices
- Keep outputs deterministic and auditable.
- Prefer small reversible changes over broad risky edits.
- Record assumptions explicitly.

## References
- Project standards: `.agent-skills/skill-standardization/SKILL.md`
- Validator script: `.agent-skills/skill-standardization/scripts/validate_skill.sh`