# Triage

> Triage issues through a state machine of triage roles. Works with GitHub (`gh`) and Jira (`acli`). Use when user wants to triage issues, review incoming bugs/features, prepare issues for an AFK agent, investigate a bug and file a ticket with a TDD fix plan, or manage issue workflow.

- Skill: `redpanda-data/triage` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add redpanda-data/triage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/redpanda-data/triage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: redpanda-data (https://skillmd.com/u/redpanda-data)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/redpanda-data/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`](./tracker-github.md)
- **Jira** (Atlassian-style ticket IDs in branches/commits, or `.atlassian/` config) -> use [`acli`](./tracker-jira.md)

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](./tracker-github.md) -- GitHub commands via `gh`
- [tracker-jira.md](./tracker-jira.md) -- Jira commands via `acli`
- [AGENT-BRIEF.md](./AGENT-BRIEF.md) -- how write durable agent briefs
- [OUT-OF-SCOPE.md](./OUT-OF-SCOPE.md) -- the `.out-of-scope/` knowledge base
- [REFERENCE.md](./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](./REFERENCE.md).

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](./AGENT-BRIEF.md))
   - `ready-for-human` -> same structure, but note why can't delegate
   - `needs-info` -> post triage notes (see [REFERENCE.md](./REFERENCE.md))
   - `wontfix` (bug) -> polite explanation, then close
   - `wontfix` (enhancement) -> write to `.out-of-scope/`, link from comment, then close ([OUT-OF-SCOPE.md](./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](./REFERENCE.md#state-machine).