Issue Breakdown (To-Issues)
Relevant source files
The following files were used as context for generating this wiki page:
Issue Breakdown (To-Issues) converts high-level plans, specifications, or Product Requirements Documents (PRDs) into granular, independently-actionable issues. The system uses a vertical slice (tracer bullet) methodology to ensure each issue delivers a verifiable end-to-end path through the system architecture rather than isolating layers like the UI or database.
This process integrates with the project's issue tracker and triage roles established during the Setup Matt Pocock Skills process. It ensures that complex features are decomposed into manageable implementation tickets that enter a standardized Triage flow.
Sources: skills/to-issues/SKILL.md:1-8, skills/setup-matt-pocock-skills/SKILL.md:6-14
Core Methodology: Vertical Slices
The breakdown process prioritizes tracer bullets over horizontal architectural layers. Each issue must cut through all integration layers, including schema, API, UI, and tests.
Slice Categories
| Slice Type | Description | Usage |
|---|---|---|
| AFK | Away From Keyboard. Can be implemented and merged without human interaction. | Preferred for routine implementation tasks. |
| HITL | Human In The Loop. Requires architectural decisions, design reviews, or human context. | Used for high-level design or ambiguous requirements. |
Sources: skills/to-issues/SKILL.md:21-27
Vertical Slice Rules
- A slice delivers a complete path through every layer.
- A completed slice is demoable or verifiable on its own.
- The agent prefers many thin slices over few thick ones.
Sources: skills/to-issues/SKILL.md:29-33
Workflow Process
The process follows five distinct steps to move from source material to published tickets.
The diagram shows the logical flow from gathering requirements to publishing issues on a tracker.
Sources: skills/to-issues/SKILL.md:14-55
1. Context Gathering
The system reads the conversation context or specific issue references (URLs or paths). It identifies the source material, such as a PRD or a plan, to understand the required features.
Sources: skills/to-issues/SKILL.md:16-19
2. Codebase Exploration
The agent explores the repository to align issue descriptions with the project's domain glossary and existing Architectural Decision Records (ADRs).
Sources: skills/to-issues/SKILL.md:21-23
3. Drafting and User Quiz
The agent presents a numbered list of slices for user approval. Each slice entry includes the title, type (HITL/AFK), blockers, and user stories covered. The agent asks the user to confirm granularity and dependency relationships.
Sources: skills/to-issues/SKILL.md:35-46
4. Publishing
Upon approval, the agent publishes issues in dependency order (blockers first) to the issue tracker. Each issue receives the needs-triage label.
Sources: skills/to-issues/SKILL.md:48-52
Issue Structure and Templates
Published issues follow a standard template to provide clarity for both humans and AFK agents.
Published Issue Format
## Parent
[Reference to source issue/PRD]
## What to build
[Concise end-to-end behavior description]
## Acceptance criteria
- [ ] Criterion 1
- [ ] Criterion 2
## Blocked by
[Reference to blocking ticket or "None"]
Sources: skills/to-issues/SKILL.md:54-70
Integration with Issue Trackers
The breakdown process supports multiple tracker environments configured via repository metadata.
| Tracker Type | Storage Location | Workflow |
|---|---|---|
| GitHub | GitHub Issues | Uses gh CLI for issue creation. |
| GitLab | GitLab Issues | Uses glab CLI for issue management. |
| Local Markdown | .scratch/<feature>/ | Creates numbered markdown files (e.g., 01-slug.md). |
Sources: skills/setup-matt-pocock-skills/SKILL.md:24-34, skills/setup-matt-pocock-skills/issue-tracker-local.md:3-16
Triage Role Mapping
Every issue published by to-issues enters the state machine with the needs-triage role. This aligns the breakdown with the standard project lifecycle.
This diagram illustrates how issues created by the breakdown process move through the triage state machine.
Sources: skills/triage/SKILL.md:14-30, skills/to-issues/SKILL.md:50-51
Technical Requirements for Breakdown
To perform a breakdown, the agent must have access to the following configuration blocks usually found in CLAUDE.md or AGENTS.md:
- Issue Tracker: Defines the destination for published slices.
- Triage Labels: Maps the canonical
needs-triagerole to the tracker's specific label strings. - Domain Docs: Provides the glossary and ADR locations to ensure technical accuracy in issue descriptions.
Sources: skills/setup-matt-pocock-skills/SKILL.md:6-14, skills/setup-matt-pocock-skills/SKILL.md:94-110
Issue Breakdown (To-Issues) serves as the bridge between high-level architectural planning and daily execution. By enforcing vertical slices and dependency ordering, it ensures that project growth remains verifiable and manageable for both human developers and autonomous agents.