issue-decomposition
Use when an issue is too large for a single task - breaks into linked sub-issues with full documentation, ensuring manageable work units
When & Why to Use This Skill
The Issue Decomposition skill is a powerful project management tool designed for software development workflows. it enables Claude to systematically break down complex, high-level GitHub issues into smaller, actionable sub-tasks. By automating the creation of linked issues, documentation, and dependency mapping, it ensures that large projects remain manageable, transparent, and compatible with AI context limits, ultimately accelerating delivery and reducing technical debt.
Use Cases
- Complex Feature Engineering: Automatically splitting a broad feature request (e.g., 'Build a Payment Gateway') into specific, trackable tasks like database migration, API integration, and frontend validation.
- Sprint Planning & Backlog Grooming: Converting vague project 'Epics' into a structured hierarchy of GitHub issues with clear acceptance criteria and verification steps.
- Legacy Code Refactoring: Managing large-scale refactoring by isolating independent code areas into individual sub-issues to minimize risk and simplify code reviews.
- Dependency Management: Mapping out technical sequences for multi-stage projects, ensuring that blockers are identified and tasks are executed in the correct logical order.
- AI-Assisted Development Optimization: Ensuring tasks are small enough to fit within a single AI context window, preventing performance degradation during automated coding sessions.
| name | issue-decomposition |
|---|---|
| description | Use when an issue is too large for a single task - breaks into linked sub-issues with full documentation, ensuring manageable work units |
| model | opus |
Issue Decomposition
Overview
Break large issues into manageable sub-issues. Each sub-issue should be completable in a single focused session.
Core principle: If an issue is too big, decompose it before starting work.
Announce at start: "I'm using issue-decomposition to break this large issue into manageable sub-tasks."
When to Decompose
An issue is too large when ANY of these are true:
| Indicator | Threshold |
|---|---|
| Acceptance criteria | More than 5 criteria |
| Areas touched | More than 3 unrelated code areas |
| Estimated work | More than 1 context window |
| Deliverables | Multiple independent features |
| Dependencies | Complex internal sequencing |
When in doubt, decompose. Smaller issues are better than larger ones.
The Decomposition Process
Step 1: Analyze the Parent Issue
Read the issue thoroughly and identify:
- Independent work units - Things that can be done separately
- Dependencies - What must come before what
- Natural boundaries - Logical separation points
- Acceptance criteria groupings - Which criteria relate to each other
Step 2: Plan Sub-Issues
Create a decomposition plan:
## Decomposition Plan for #[PARENT_NUMBER]
### Sub-Issue 1: [Title]
**Criteria from parent:** 1, 2
**Dependencies:** None
**Deliverable:** [What this sub-issue delivers]
### Sub-Issue 2: [Title]
**Criteria from parent:** 3, 4
**Dependencies:** Sub-Issue 1
**Deliverable:** [What this sub-issue delivers]
### Sub-Issue 3: [Title]
**Criteria from parent:** 5
**Dependencies:** Sub-Issue 2
**Deliverable:** [What this sub-issue delivers]
Step 3: Create Sub-Issues
For each sub-issue:
gh issue create \
--title "[Type] [Parent Title] - [Sub-Task Title]" \
--body "## Description
Part of #[PARENT_NUMBER]: [Parent Title]
[Specific description of this sub-task]
## Acceptance Criteria
- [ ] [Criterion 1 - copied or derived from parent]
- [ ] [Criterion 2]
## Verification Steps
[How to verify this specific sub-task]
## Dependencies
- Requires: #[PREVIOUS_SUB_ISSUE] (if any)
- Blocks: #[NEXT_SUB_ISSUE] (if any)
## Parent Issue
Closes part of #[PARENT_NUMBER]"
Step 4: Label and Link
# Label sub-issues
gh issue edit [SUB_ISSUE_NUMBER] --add-label "sub-issue"
# Label parent
gh issue edit [PARENT_NUMBER] --add-label "parent"
Step 5: Update Parent Issue
Add to the parent issue body:
## Sub-Issues
This issue has been broken down into:
- [ ] #[SUB_1] - [Title]
- [ ] #[SUB_2] - [Title]
- [ ] #[SUB_3] - [Title]
Complete all sub-issues to resolve this parent issue.
Step 6: Add to Project
# Add all sub-issues to project
gh project item-add [PROJECT_NUMBER] --owner @me --url [SUB_ISSUE_1_URL]
gh project item-add [PROJECT_NUMBER] --owner @me --url [SUB_ISSUE_2_URL]
# etc.
# Set status to Ready (or Backlog if blocked)
Step 7: Update Memory
Store the decomposition in knowledge graph:
Entity: Issue [PARENT_NUMBER]
Observation: "Decomposed into sub-issues [X], [Y], [Z] on [DATE]"
Relations:
- Issue [PARENT] --has_sub_issue--> Issue [SUB_1]
- Issue [SUB_1] --blocks--> Issue [SUB_2]
Sub-Issue Quality Checklist
Each sub-issue MUST have:
- Clear title indicating it's part of parent
- Reference to parent issue in description
- Own acceptance criteria (not just "see parent")
- Own verification steps
- Dependencies documented (if any)
- Added to GitHub Project
- Labeled as
sub-issue
Handling Dependencies
When sub-issues have dependencies:
| Dependency Type | Project Status | Notes |
|---|---|---|
| No dependencies | Ready | Can start immediately |
| Blocked by another sub-issue | Backlog | Move to Ready when blocker completes |
| Blocks another sub-issue | Ready | Work on this first |
After Decomposition
Once decomposition is complete:
- Update memory with decomposition record
- Return to Step 1 of
issue-driven-developmentwith first sub-issue - Work through sub-issues in dependency order
- Close parent issue when all sub-issues are done
Example Decomposition
Parent Issue: #100 - Implement user authentication
Sub-Issues Created:
| # | Title | Dependencies | Criteria |
|---|---|---|---|
| 101 | Auth - Database schema | None | User table, session table |
| 102 | Auth - Registration endpoint | #101 | Signup, validation, storage |
| 103 | Auth - Login endpoint | #101 | Login, session creation |
| 104 | Auth - Logout endpoint | #103 | Session invalidation |
| 105 | Auth - Protected route middleware | #103 | Auth check, redirect |
| 106 | Auth - UI integration | #102, #103, #104, #105 | Forms, state, routing |
Common Mistakes
| Mistake | Correction |
|---|---|
| Sub-issues too vague | Each sub-issue needs specific, verifiable criteria |
| Missing dependencies | Map out order before creating sub-issues |
| Not updating parent | Parent must list all sub-issues |
| Skipping project setup | Each sub-issue must be in project with correct status |
| Criteria duplicated wrong | Derive specific criteria, don't just copy all |