| name | triage-workflow |
| description | Label-based state machine for triaging issues and work items. Manages state transitions, generates durable triage artifacts, and supports resumable sessions. Use when triaging GitHub issues or Azure DevOps work items. Do not use for creating new work items from scratch (use work-item-creation) or for managing implementation workflow of already-triaged items (use work-item-workflow). |
Triage Workflow
State Machine
States
| State | Description |
|---|
unlabeled | New issue, never triaged |
needs-triage | Maintainer needs to evaluate |
needs-info | Waiting on reporter for more information |
ready-for-agent | Fully specified, ready for autonomous agent implementation |
ready-for-human | Requires human implementation |
wontfix | Will not be actioned |
Every issue should have exactly one state label. If conflicting state labels exist, flag the conflict and ask the maintainer which is correct.
Transitions
| From | To | Who triggers | What happens |
|---|
unlabeled | needs-triage | Skill (first look) | Issue needs evaluation; apply label |
unlabeled | ready-for-agent | Maintainer | Well-specified, agent-suitable; write agent brief, apply label |
unlabeled | ready-for-human | Maintainer | Requires human; write summary, apply label |
unlabeled | wontfix | Maintainer | Out of scope or duplicate; close with comment |
needs-triage | needs-info | Maintainer | Underspecified; post triage notes with questions |
needs-triage | ready-for-agent | Maintainer | Clarification complete, agent-suitable; write agent brief |
needs-triage | ready-for-human | Maintainer | Clarification complete, needs human; write summary |
needs-triage | wontfix | Maintainer | Decided not to action; close with comment |
needs-info | needs-triage | Skill (detects reply) | Reporter replied; resurface for re-evaluation |
Only these transitions are valid. Flag unusual transitions.
Content Style
Triage notes, agent briefs, summaries, comments, and any label-driven artifacts written to the board follow the Content Style rules in the work-item-creation skill: no emojis or decorative Unicode, no em-dash or hyphen as separator between concepts, never #<number> in free text (Azure DevOps auto-links it), no contrastive framing, direct active voice, no promotional language, short concrete prose.
When this skill writes any content to GitHub or Azure DevOps (state-change comments, agent briefs, info requests), apply those rules before sending.
Platform Adaptation
GitHub Issues
State is managed via labels:
| Label | Color (hex) |
|---|
needs-triage | fbca04 |
needs-info | d93f0b |
ready-for-agent | 0e8a16 |
ready-for-human | 1d76db |
wontfix | e4e669 |
When transitioning: remove old state label, add new state label. Ensure the category label (bug or enhancement) is also present.
Azure DevOps
Map states to the process template's workflow states (per board-config). Use tags for supplementary classification (ready-for-agent, needs-info).
Output Artifacts
Agent Brief (for ready-for-agent)
Post as a comment on the issue:
> This was generated by AI during triage.
## Agent Brief
**Objective**: [What needs to be built or fixed, in domain language]
**Acceptance criteria**:
- [ ] [Criterion 1]
- [ ] [Criterion 2]
**Context**: [What the agent needs to know about the codebase area]
**Constraints**: [Any limits on the approach]
Durability rules apply: no file paths, no line numbers. Describe behavior and domain concepts.
Triage Notes (for needs-info)
Post as a comment:
> This was generated by AI during triage.
## Triage Notes
**What we have established so far:**
- [Point 1]
- [Point 2]
**What we still need from you (@reporter):**
- [Specific, actionable question 1]
- [Specific, actionable question 2]
Include everything resolved during the clarification session. Questions must be specific, not vague ("please provide more info").
Human Brief (for ready-for-human)
Post as a comment with the same structure as agent brief, plus:
**Why this needs human implementation**: [Reason: judgment calls, external system access, design decisions, manual testing]
Closure Comment (for wontfix)
Post a polite comment explaining why, then close the issue.
Durability Rules
All triage artifacts follow the durability rules from the work-item-creation skill:
- Describe behavior using domain language
- Do not reference file paths, line numbers, or internal module names
- Implementation context belongs in linked PRs and commits
Anti-patterns
- Do not triage issues without reading the full body and all comments
- Do not skip bug reproduction for bug-categorized issues
- Do not post triage notes that lose progress from previous sessions
- Do not ask vague questions in needs-info comments ("can you provide more details?")
- Do not apply state labels without also posting the corresponding artifact (brief, notes, or closure comment)
