Triage Process
Relevant source files
The following files were used as context for generating this wiki page:
The triage process moves issues through a structured state machine to prepare them for implementation. It categorizes incoming requests, validates bugs through reproduction, and generates authoritative specifications for agents or humans to follow. The system relies on a standardized set of labels and roles to track the lifecycle of an issue from initial report to being ready for work.
Sources: skills/triage/SKILL.md:1-12, skills/setup-matt-pocock-skills/SKILL.md:38-51
Triage Roles and State Machine
The system uses two category roles and five state roles to manage the issue workflow. Every triaged issue must carry exactly one category role and one state role.
Category Roles
- bug: Indicates something in the system is broken.
- enhancement: Indicates a new feature or improvement request.
Sources: skills/triage/SKILL.md:21-24
State Roles
The following table describes the canonical state roles used to track progress:
| Role | Meaning |
|---|---|
needs-triage | The maintainer needs to evaluate the issue. This is the default state for unlabeled issues. |
needs-info | The system is waiting on the reporter for more information. Returns to needs-triage when they reply. |
ready-for-agent | The issue is fully specified and ready for an AFK (Away From Keyboard) agent. |
ready-for-human | The issue requires human implementation due to judgment calls, manual testing, or restricted access. |
wontfix | The issue will not be actioned. |
Sources: skills/triage/SKILL.md:26-37, skills/setup-matt-pocock-skills/triage-labels.md:7-12
State Transitions
Issues follow a logical flow through these states. A maintainer can override transitions at any time, but unusual transitions should be flagged for review.
The diagram shows the standard flow of an issue through the triage state machine.
Sources: skills/triage/SKILL.md:34-37
Triage Workflow Steps
When a maintainer invokes the triage process, the system follows a specific sequence to evaluate and move issues forward.
1. Context Gathering
The system reads the full issue body, comments, labels, and reporter details. It explores the codebase using the project domain glossary and checks the .out-of-scope/ knowledge base for similar prior rejections.
Sources: skills/triage/SKILL.md:52-56, skills/triage/OUT-OF-SCOPE.md:37-43
2. Bug Reproduction
For issues categorized as bugs, the system attempts to reproduce the reported behavior by:
- Reading the reporter's steps.
- Tracing relevant code paths.
- Running tests or commands.
Reproduction outcomes determine the next state: a confirmed repro strengthens the case for ready-for-agent, while a failed repro signals needs-info.
Sources: skills/triage/SKILL.md:60-63
3. Out-of-Scope Management
When an enhancement is rejected as wontfix, the system captures the decision in the .out-of-scope/ directory. This creates a persistent record to avoid re-litigating the same feature requests in the future.
The diagram illustrates the process of archiving rejected enhancements in the out-of-scope knowledge base.
Sources: skills/triage/OUT-OF-SCOPE.md:46-55
Triage Outputs
The triage process results in specific artifacts depending on the final state of the issue.
Agent Briefs
When an issue moves to ready-for-agent, an authoritative Agent Brief is posted. This brief serves as the contract for the AFK agent and must be durable, behavioral (describing what not how), and include testable acceptance criteria.
Brief Structure:
- Category: Bug or Enhancement.
- Summary: One-line description.
- Current/Desired Behavior: Contrast between status quo and goal.
- Key Interfaces: Types, function signatures, or config shapes.
- Acceptance Criteria: Checkbox list of testable outcomes.
- Out of Scope: Explicit boundaries.
Sources: skills/triage/AGENT-BRIEF.md:1-50
Triage Notes
When an issue moves to needs-info, the system uses a template to clarify established facts versus outstanding questions.
## Triage Notes
**What we've established so far:**
- [Resolved Point]
**What we still need from you (@reporter):**
- [Specific Actionable Question]
Sources: skills/triage/SKILL.md:79-88
System Setup and Configuration
Before triage can occur, the repository must be configured using the setup-matt-pocock-skills skill. This establishes the issue tracker location (GitHub, GitLab, or Local Markdown) and maps the canonical triage roles to the specific label strings used in the tracker.
Sources: skills/setup-matt-pocock-skills/SKILL.md:7-14, skills/setup-matt-pocock-skills/triage-labels.md:5-13
Summary
The Triage Process ensures that issues are accurately categorized and sufficiently detailed before implementation begins. By utilizing a formal state machine, reproduction steps, and structured agent briefs, the project maintains a high standard of specification that allows for both human and autonomous agent contributions.