github-issue-breakdown

name	github-issue-breakdown
description	Break down GitHub issues into official GitHub sub-issues by parsing task lists from parent issue descriptions. Use this skill when a user wants to convert a parent issue with tasks into linked sub-issues, when managing complex features that need hierarchical breakdown. Accepts issue number as parameter or prompts user if not provided.

GitHub Issue Breakdown

Overview

This skill automates breaking down GitHub issues into official GitHub sub-issues using the GitHub GraphQL API. It parses various task list formats from parent issue descriptions, shows a preview of proposed sub-issues, and creates them with proper parent-child relationships while inheriting metadata like labels and assignees.

When to Use This Skill

⚠️ CRITICAL: Use this skill IMMEDIATELY after creating an Epic/parent issue with a task list!

DO NOT manually create sub-issues - they won't have proper GitHub parent-child relationships and won't show in the sub-issue UI.

Use this skill when:

• Right after creating an Epic - Run this immediately to create official sub-issues ⭐ MOST IMPORTANT
• User requests breaking down an issue into sub-tasks (e.g., "break down issue #47 into sub-issues")
• User mentions converting a task list into sub-issues
• User is working with complex features that need hierarchical task management
• User needs to create multiple related child issues from a parent issue

Invocation patterns:

• "Break down issue #42 into sub-tasks"
• "Create sub-issues from issue 47"
• "Convert the task list in issue #42 to sub-issues"
• "Use github-issue-breakdown on issue 42"

⚠️ Common Mistake to Avoid:

❌ WRONG - Creates informal sub-tasks WITHOUT parent-child links:

# Create epic
gh issue create --title "Epic: Feature X"

# Manually create sub-issues (NO PARENT-CHILD LINK!)
gh issue create --title "Phase 1" --body "Sub-task of #42"
gh issue create --title "Phase 2" --body "Sub-task of #42"
# Result: Issues exist but aren't real sub-issues

✅ CORRECT - Creates official sub-issues WITH parent-child links:

# Create epic with task list
gh issue create --title "Epic: Feature X" --body "## Tasks
- [ ] Phase 1: Setup
- [ ] Phase 2: Implementation"

# IMMEDIATELY use this skill to create official sub-issues
python scripts/create_subissues.py --issue 42 --yes
# Result: Proper sub-issues that show in GitHub UI

Why this matters:

• Manual issues only have informal text links ("Sub-task of #X")
• They don't show in GitHub's sub-issue UI
• No automatic tracking of parent-child relationships
• Can't use GitHub's task completion features
• Harder to track Epic progress
• Must be recreated to fix (GitHub doesn't support retroactive conversion)

Quick Start

Prerequisites

1. Environment Variables:

   export GITHUB_TOKEN="ghp_xxxx"      # GitHub token with repo scope
   

2. Token Scopes:

   • GITHUB_TOKEN - Requires repo scope for issue operations
   • Must have write access to the repository

3. Setup Location: Configure in .devcontainer/.env (gitignored):

   GITHUB_TOKEN=your_token_here
   

Basic Usage

# Break down an issue (interactive - will show preview)
python /workspace/.claude/skills/github-issue-breakdown/scripts/create_subissues.py --issue 42

# Specify repository explicitly
python /workspace/.claude/skills/github-issue-breakdown/scripts/create_subissues.py --issue 42 --repo owner/repo

# Dry-run mode (preview only, no creation)
python /workspace/.claude/skills/github-issue-breakdown/scripts/create_subissues.py --issue 42 --dry-run

Task Workflows

Task 1: Break Down Issue with Parameter

When user provides an issue number in their request:

1. Extract issue number from user request:

   User: "Break down issue #42 into sub-tasks"
   

2. Execute the script:

   cd /workspace/.claude/skills/github-issue-breakdown
   python scripts/create_subissues.py --issue 42
   

3. Script workflow:

   • Auto-detects current repository from git context
   • Fetches parent issue content
   • Parses task lists (markdown checkboxes, numbered lists, bullets)
   • Shows preview of proposed sub-issues
   • Asks for confirmation
   • Creates sub-issues with parent-child relationships
   • Reports results with URLs

4. Example output:

   Repository: codekiln/langstar
   Parent Issue: #42 - Add user authentication
   
   Found 4 tasks to convert into sub-issues:
   
   1. Create login endpoint
   2. Create registration endpoint
   3. Implement JWT token generation
   4. Add authentication middleware
   
   Create these 4 sub-issues? (y/n):
   

Task 2: Break Down Issue Without Parameter

When user requests breakdown but doesn't specify which issue:

1. Recognize the request:

   User: "Break down this issue into sub-tasks"
   User: "Create sub-issues from the task list"
   

2. Ask user for issue number: Use the AskUserQuestion tool to prompt for the issue number.

3. Execute with provided issue number:

   python scripts/create_subissues.py --issue <user_provided_number>
   

Task 3: Preview Sub-Issues (Dry Run)

When user wants to see what would be created without actually creating:

1. Execute in dry-run mode:

   python scripts/create_subissues.py --issue 42 --dry-run
   

2. Script will:

   • Show all parsed tasks
   • Display what sub-issues would be created
   • Show inherited metadata (labels, assignees)
   • Exit without creating anything

Script Details

Location

/workspace/.claude/skills/github-issue-breakdown/scripts/create_subissues.py
/workspace/.claude/skills/github-issue-breakdown/scripts/gh_helpers.py

Arguments

Argument	Required	Description	Example
--issue	Yes	Issue number to break down	--issue 42 or --issue 47
--repo	No	Repository (auto-detected if not provided)	--repo codekiln/langstar
--dry-run	No	Preview mode without creating	--dry-run
--inherit-labels	No	Inherit labels from parent (default: true)	--inherit-labels
--inherit-assignees	No	Inherit assignees from parent (default: true)	--inherit-assignees
--section	No	Only parse under this section header	--section "Implementation Tasks"
--checkbox-only	No	Only parse checkboxes - [ ], ignore bullets/numbers	--checkbox-only
--max-depth	No	Maximum indentation depth (0 = top-level, default: 0)	--max-depth 1
--all-bullets	No	Disable section filtering (legacy behavior)	--all-bullets
--yes, -y	No	Auto-confirm creation without prompting	--yes

Environment Variables

Required:

• GITHUB_TOKEN - Fine-grained or classic PAT with repo scope

Optional:

• GH_TOKEN - Alternative name for GitHub token (fallback)

What the Script Does

1. Auto-detects repository - Uses git context to determine owner/repo
2. Fetches parent issue - Retrieves issue title, body, labels, assignees via GraphQL
3. Parses task lists - Supports multiple formats (see Parsing Patterns)
4. Shows preview - Displays proposed sub-issues with inherited metadata
5. Confirms with user - Waits for confirmation before creating
6. Creates sub-issues - Uses GraphQL createIssue mutation with parentIssueId
7. Reports results - Shows success/failure for each sub-issue with URLs

Script Behavior

• Interactive - Shows preview and waits for confirmation
• Idempotent - Safe to run dry-run multiple times
• Error handling - Reports specific errors for each sub-issue
• Repository-agnostic - Works in any repository without modification
• Portable - No hardcoded repository or project IDs
• Context-aware parsing - By default, only parses tasks under dedicated task sections

Best Practices for Parent Issues

The skill uses context-aware parsing by default. Structure your parent issues properly for best results:

✅ Good Structure

Place your tasks under a dedicated section header:

## Overview
Detailed description of the feature...

## Implementation Tasks

- [ ] Phase 1: Research & Experimentation
- [ ] Phase 2: SDK Layer
- [ ] Phase 3: CLI Layer
- [ ] Phase 4: Testing

## Background
Any explanatory content here won't be parsed as tasks.

## Configuration Details
- **Environment variables**: FOO_BAR (won't be parsed - not under Tasks section)
- **Config file**: settings.toml (won't be parsed)

Why this works:

• Tasks are clearly separated under ## Implementation Tasks header
• Explanatory bullets elsewhere are ignored
• Section headers like "Tasks", "Sub-Issues", "Implementation Tasks", "Sub-Tasks" are auto-detected

❌ Avoid This Structure

Don't use bullets for non-task content throughout your issue:

## Configuration Methods
- **Environment variables**: FOO (this will be parsed as a task!)
- **Config file**: bar.toml (this will be parsed as a task!)
- **CLI flags**: --flag (this will be parsed as a task!)

## Behavior
- When condition X happens (this will be parsed as a task!)
- Need explicit flag Y (this will be parsed as a task!)

Why this fails:

• Without section filtering, ALL bullets become tasks
• Configuration options become "sub-issues"
• Explanatory text becomes "sub-issues"
• Results in 50+ unwanted sub-issues

How to fix:

• Use paragraphs for explanatory content instead of bullets
• Or use --section "Tasks" to explicitly specify which section contains actual tasks
• Or restructure to have a dedicated "Tasks" section

Common Pitfalls

Pitfall 1: Over-Parsing Complex Spec Documents

Problem: Issue has 100+ lines with bullets for formatting, configuration options, and explanations.

Symptom: Script finds 50+ tasks when you only want 5-10.

Solution:

1. Use --dry-run first to preview what will be parsed
2. Add a dedicated ## Tasks or ## Implementation Tasks section
3. Or use --section "Phase Tasks" to target specific section
4. Or use --checkbox-only for strict checkbox-only parsing

Pitfall 2: Nested Task Lists

Problem: Issue has multi-level nested tasks with sub-items.

Symptom: All nested items become separate sub-issues.

Solution:

• By default, only top-level items (indent 0) are parsed
• Nested items are automatically skipped
• Use --max-depth 1 if you want one level of nesting

Pitfall 3: Using Bullets for Everything

Problem: Using - for all content (explanations, options, tasks).

Symptom: Everything becomes a task.

Solution:

• Reserve bullets for actual tasks only
• Use prose paragraphs for explanations
• Structure issue with dedicated task section
• Or use checkbox-only mode: --checkbox-only

Troubleshooting

Issue: Too Many Tasks Parsed

Symptom: Script finds 50+ tasks but you only have 5-10 actual tasks.

Diagnosis: The parser is picking up explanatory bullets, configuration options, or nested details.

Solutions:

1. Preview first: --dry-run to see what's being parsed
2. Add task section: Restructure issue with ## Tasks header
3. Target specific section: Use --section "Implementation Tasks"
4. Strict mode: Use --checkbox-only to only parse - [ ] items
5. Check for nesting: Verify indented items aren't being parsed (they shouldn't be by default)

Example:

# Preview what will be created
python scripts/create_subissues.py --issue 46 --dry-run

# Only parse under "Implementation Tasks" section
python scripts/create_subissues.py --issue 46 --section "Implementation Tasks"

# Strict checkbox-only mode
python scripts/create_subissues.py --issue 46 --checkbox-only

Issue: No Tasks Found

Symptom: Script reports "No tasks found" but issue clearly has tasks.

Diagnosis: Tasks aren't under a recognized section header.

Solutions:

1. Check section header: Ensure tasks are under ## Tasks, ## Sub-Issues, or similar
2. Specify section explicitly: Use --section "Your Custom Header"
3. Disable filtering: Use --all-bullets to parse all bullets (legacy behavior)
4. Verify format: Ensure using supported formats (- [ ], 1., *, -)

Example:

# Parse under custom section header
python scripts/create_subissues.py --issue 46 --section "Phase List"

# Disable section filtering (parse all bullets)
python scripts/create_subissues.py --issue 46 --all-bullets

Issue: Warning About 20+ Tasks

Symptom: Script warns "Found more than 20 tasks" and suggests alternatives.

Diagnosis: Likely over-parsing explanatory content.

What to do:

1. Run --dry-run to review what's being parsed
2. Restructure issue to have clear task section
3. Use --section or --checkbox-only for stricter parsing
4. If truly 20+ tasks, proceed with caution or break down further

Issue: Sub-Issues Not Showing in GitHub UI

Symptom: Issues created but don't show as "sub-issues" on parent issue.

Diagnosis: Only affects manually created issues via gh issue create (which doesn't support parent relationships).

Solution: Always use this skill's script - it's the only CLI way to create proper parent-child relationships. The script uses GraphQL createIssue with parentIssueId parameter.

Parsing Patterns

The skill supports multiple task list formats. For detailed documentation, load references/parsing-patterns.md into context.

Quick reference:

• Markdown checkboxes: - [ ] Task name
• Markdown checked boxes: - [x] Task name (skipped by default)
• Numbered lists: 1. Task name
• Bullet points: * Task name or - Task name

Common Use Cases

Use Case 1: Feature Development with Sub-Tasks

User says: "Break down issue #42 (Add authentication) into sub-tasks"

Execute:

python scripts/create_subissues.py --issue 42

Result: Creates sub-issues for each task in the parent issue description.

Use Case 2: Preview Before Creating

User says: "Show me what sub-issues would be created from issue #47"

Execute:

python scripts/create_subissues.py --issue 47 --dry-run

Result: Shows preview without creating anything.

Use Case 3: Cross-Repository Sub-Issues

User says: "Create sub-issues from issue #10 in my other-repo"

Execute:

python scripts/create_subissues.py --issue 10 --repo username/other-repo

Result: Creates sub-issues in specified repository.

Tips for Effective Usage

1. Check parent issue format - Ensure parent issue has clear task list
2. Use dry-run first - Preview before creating to verify parsing
3. Support multiple formats - Script handles various task list styles
4. Inherit metadata by default - Sub-issues get parent labels and assignees
5. Repository auto-detection - Works automatically in any git repository
6. Confirmation required - Script always asks before creating
7. Review created sub-issues - Check URLs in output to verify
8. Integration with workflows - Complements GitHub Projects

Integration with Existing Workflow

This skill enhances the project's GitHub issue-driven development workflow:

Standard Workflow:

1. Create parent issue (existing)
2. NEW: Use this skill to break down into sub-issues
3. Create branch for sub-issue work (existing)
4. Development (existing)
5. Create PR (existing)
6. Review & Merge (existing)

References

This skill includes reference documentation:

• references/parsing-patterns.md - Detailed documentation of supported task list formats

Load reference files into context when needing detailed information about parsing logic or troubleshooting parsing issues.