decompose

name	decompose
description	Decompose a large GitHub issue into sub-issues and create a tracking draft PR
argument-hint	<issue-number>
user-invocable	true

Issue Decomposition Skill

Help the user break down a large GitHub issue into manageable sub-issues, tracked via a draft PR.

Input

The user provides an issue number: $ARGUMENTS

Workflow

Step 1: Fetch and Analyze the Issue

~/.claude/bin/gh-save.sh /tmp/issue-$ARGUMENTS.json issue view $ARGUMENTS --json title,body,labels,milestone

Use the Read tool to read /tmp/issue-$ARGUMENTS.json. Analyze the issue body to identify:

• Phases/Sections: Look for headers, checklists, numbered lists
• Dependencies: Which tasks must complete before others
• Logical groupings: Backend vs frontend, foundation vs features

Step 2: Propose Sub-Issue Breakdown

Present a table to the user:

## Proposed Sub-Issues for #[issue-number]

| # | Sub-Issue Title | Depends On | Scope |
|---|-----------------|------------|-------|
| 1 | Phase 1: [Foundation/Setup] | - | Backend/Frontend/Both |
| 2 | Phase 2: [Core Feature] | #1 | ... |
| 3 | Phase 3: [Integration] | #1, #2 | ... |
| ... | ... | ... | ... |

Does this breakdown look correct? I can:
- **A)** Create these sub-issues now
- **B)** Adjust the breakdown first
- **C)** Just create the draft PR template (no sub-issues yet)

Step 3: Create Branch (if needed)

Check if branch exists:

git fetch origin
git branch -a --list "*issue-$ARGUMENTS*"

If no branch exists, ask if user wants to create it:

git checkout -b issue-$ARGUMENTS-[feature-name]

Step 4: Create Draft PR

Use this template structure:

IMPORTANT: The Closes statements must include BOTH the parent issue AND all sub-issues. When creating the PR initially (before sub-issues exist), start with just Closes #[issue-number]. After creating sub-issues in Step 5, update the PR body to add Closes #[sub-issue-N] for each sub-issue (see Step 5d).

Closes #[issue-number]

This PR tracks the complete [feature name] implementation across all sub-issues.

---

## Parent Issue Progress

[Brief description of what this implements]

### Sub-Issues

| # | Sub-Issue | Status | PR |
|---|-----------|--------|-----|
| 1 | #XXX - [Title] | ⏳ Pending | - |
| 2 | #XXX - [Title] | ⏳ Pending | - |
| ... | ... | ... | ... |

**Progress:** 0 of N sub-issues complete (0%)

---

## Branch Structure

develop ↑ issue-[number]-[feature] (this PR) ↑ (sub-branches will be added as work progresses)

---

## Implementation Phases

### Phase 1: [Name]
- [ ] Task 1
- [ ] Task 2

### Phase 2: [Name]
- [ ] Task 3
- [ ] Task 4

---

## Related Issues
- [List any related/blocking issues]

---

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

Step 5: Create Sub-Issues (if user confirms)

For each sub-issue, first write the body using the Write tool to /tmp/sub-issue-<n>.md:

Parent issue: #[parent-number]

## Scope
[What this sub-issue covers]

## Tasks
- [ ] Task 1
- [ ] Task 2

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Dependencies
- Blocked by: [POSITION-ref, e.g. §2 — see note below, or "None"]
- Blocks: [POSITION-ref, e.g. §3 — see note below, or "None"]

CRITICAL — cross-references are POSITION placeholders, not issue numbers. When you write a sub-issue body in this step, the real issue numbers of the OTHER sub-issues do not exist yet (gh issue create below is what mints them). Any Blocked by / Blocks reference to a sibling sub-issue is therefore only a position in the Step 2 table. Never write #2/#3 here — a bare #2 is a real, unrelated issue in the repo and will silently point at the wrong thing. Instead write the position with a non-# marker that is unambiguous to find and replace later — e.g. §2 / §3 (or sub-2 / sub-3). Step 5e rewrites these into the real #-numbers once they are known.

Then create the issue:

gh issue create --title "[Parent #] Sub-issue: [Title]" --body-file /tmp/sub-issue-<n>.md

Record the mapping position → real number as each gh issue create returns its URL/number (e.g. §1 → #146, §2 → #147, §3 → #148). Step 5e needs this.

Step 5b: Link as Native GitHub Sub-Issues

After creating all sub-issues, link them to the parent issue using the GitHub GraphQL API:

1. Fetch the node IDs for parent and all sub-issues in one query:

gh api graphql -f query='
{
  repository(owner: "OWNER", name: "REPO") {
    parent: issue(number: [parent-number]) { id }
    sub1: issue(number: [sub-number-1]) { id }
    sub2: issue(number: [sub-number-2]) { id }
    ...
  }
}'

2. Link each sub-issue to the parent:

gh api graphql -f query='
mutation {
  addSubIssue(input: {issueId: "[parent-node-id]", subIssueId: "[sub-node-id]"}) {
    issue { number }
    subIssue { number }
  }
}'

Do this for ALL created sub-issues. This enables GitHub's native sub-issue tracking in the UI.

Step 5c: Verify Created Sub-Issues

After creating and linking all sub-issues, fetch their details in one batch to confirm and build the tracking table:

~/.claude/bin/batch-issue-view.sh <repo> [created-issue-numbers...]

Step 5d: Add Closes Statements to Tracking PR

Update the draft PR body to add Closes #[sub-issue-number] for each created sub-issue. This ensures all sub-issues auto-close when the tracking PR merges.

Add after the existing Closes #[parent-issue] line:

Closes #[parent-issue]
Closes #[sub-issue-1]
Closes #[sub-issue-2]
...

Also update the tracking table with the actual sub-issue numbers and titles.

Step 5e: Rewrite Cross-References to Real Issue Numbers

The sub-issue bodies still contain the §N / sub-N position placeholders from Step 5 (in their Dependencies sections). Now that every sub-issue has a real number, replace each placeholder with the real #-number using the mapping you recorded in Step 5.

For each sub-issue whose body contains a cross-reference:

1. Edit its local /tmp/sub-issue-<n>.md — replace every §K / sub-K with the real #-number for position K (e.g. §2 → #147, §3 → #148).
2. Push the corrected body back:

   gh issue edit [real-number] --body-file /tmp/sub-issue-<n>.md
   

Verify no placeholder survives. After editing, grep the bodies for a leftover marker — a stray § or sub-N means a dependency still points nowhere, and a bare #K that was never rewritten silently points at the wrong (real) issue:

grep -nE '§[0-9]|sub-[0-9]' /tmp/sub-issue-*.md   # must return nothing

If any sub-issue's Dependencies still reads #1/#2/#3 and those were meant as positions, they are wrong — rewrite them to the real numbers too.

Step 6: Update Parent Issue

Add a tracking section to the parent issue: Write the updated body to a temp file first, then use --body-file:

# Write updated body to temp file using the Write tool
# Then apply it:
gh issue edit $ARGUMENTS --body-file /tmp/issue_body.md

Example Usage

/decompose 723

This will:

1. Fetch issue #723
2. Analyze and propose sub-issues
3. Ask user for confirmation
4. Create draft PR and optionally sub-issues
5. Update parent issue with tracking table
6. Suggest refining each sub-issue

Final Step: Suggest Refinement

After all sub-issues are created, present the list with a recommendation:

Sub-issues created: #724, #725, #726

Tip: run `/refine` on each sub-issue to sharpen scope and acceptance criteria
before implementation. This catches gaps early and improves implementation quality.

/refine 724
/refine 725
/refine 726