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

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

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.
nameissue-decomposition
descriptionUse when an issue is too large for a single task - breaks into linked sub-issues with full documentation, ensuring manageable work units
modelopus

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:

  1. Independent work units - Things that can be done separately
  2. Dependencies - What must come before what
  3. Natural boundaries - Logical separation points
  4. 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]"
# 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:

  1. Update memory with decomposition record
  2. Return to Step 1 of issue-driven-development with first sub-issue
  3. Work through sub-issues in dependency order
  4. 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