Skip to content
issue-decomposition logo

Issue Decomposition

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

SKILL.md

Full skill instructions

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:

IndicatorThreshold
Acceptance criteriaMore than 5 criteria
Areas touchedMore than 3 unrelated code areas
Estimated workMore than 1 context window
DeliverablesMultiple independent features
DependenciesComplex 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]"

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 TypeProject StatusNotes
No dependenciesReadyCan start immediately
Blocked by another sub-issueBacklogMove to Ready when blocker completes
Blocks another sub-issueReadyWork 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:

#TitleDependenciesCriteria
101Auth - Database schemaNoneUser table, session table
102Auth - Registration endpoint#101Signup, validation, storage
103Auth - Login endpoint#101Login, session creation
104Auth - Logout endpoint#103Session invalidation
105Auth - Protected route middleware#103Auth check, redirect
106Auth - UI integration#102, #103, #104, #105Forms, state, routing

Common Mistakes

MistakeCorrection
Sub-issues too vagueEach sub-issue needs specific, verifiable criteria
Missing dependenciesMap out order before creating sub-issues
Not updating parentParent must list all sub-issues
Skipping project setupEach sub-issue must be in project with correct status
Criteria duplicated wrongDerive specific criteria, don't just copy all

More skills from majiayu000

xiaohongshu logo
majiayu000/claude-arsenal

xiaohongshu

xiaohongshu

286 148
View
agent-task-conductor logo
majiayu000/claude-skill-registry

agent-task-conductor

Conduct multi-agent task orchestration and workflow coordination.

663 1
View
conductor-setup logo
majiayu000/claude-skill-registry

conductor-setup

Initialize project with Conductor artifacts (product definition,

663 1
View
animation-designer logo
majiayu000/claude-skill-registry

animation-designer

Expert in web animations, transitions, and motion design using Framer Motion and CSS

663 1
View
diagramming logo
majiayu000/claude-skill-registry

diagramming

Creates Mermaid and ASCII diagrams for flowcharts, architecture, ERDs, state machines, mindmaps, and more. Use when user mentions diagram, flowchart, mermaid, ASCII diagram, text diagram, terminal diagram, visualize, C4, mindmap, architecture diagram, sequence diagram, ERD, or needs visual docume...

663 1
View
h3-pg logo
majiayu000/claude-skill-registry-data

h3-pg

PostgreSQL bindings for H3 hexagonal grid system. Use when working with H3 cells in Postgres, including spatial indexing, geometry/geography integration, and raster analysis.

23 1
View
conductor-development logo
majiayu000/claude-skill-registry

conductor-development

Context-Driven Development skill for projects using Conductor. Use this skill when you detect a `conductor/` directory in the project, when working on tasks defined in a `plan.md` file, or when the user asks about tracks, specs, or plans. Automatically applies TDD workflow, tracks task completion...

663 1
View
conductor-status logo
majiayu000/claude-skill-registry

conductor-status

Display project status, active tracks, and next actions

663 1
View
dockerization logo
majiayu000/claude-skill-registry

dockerization

Official Stakpak application containerization standard operating procedure, a step-by-step guidline to properly dockerize applications. This is a rule book curated by the Stakpak Team.

663 1
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View