troykelly/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 |