Issue decomposition

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]"

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:

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