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

Use this skill when:

• 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 wants to convert Spec-Kit generated task lists into GitHub sub-issues
• 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"

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

Task 4: Integration with Spec-Kit

When user has generated tasks using Spec-Kit:

1. Spec-Kit generates task list:

   User: "Run /speckit.tasks to generate task list"
   

2. Create issue from task list: Copy tasks from .specify/tasks/ into new GitHub issue

3. Break down the issue:

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

4. Workflow integration:

   • /speckit.specify → Define requirements
   • /speckit.plan → Create technical plan
   • /speckit.tasks → Generate task list
   • Create parent issue with tasks
   • Use this skill to create sub-issues
   • /speckit.implement → Work on sub-issues

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
• Spec-Kit format: Custom task delimiters

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: Spec-Kit Workflow Integration

User says: "I ran /speckit.tasks and created issue #50 with the task list. Create sub-issues from it."

Execute:

python scripts/create_subissues.py --issue 50

Result: Converts Spec-Kit task list into linked sub-issues.

Use Case 3: 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 4: 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 Spec-Kit and 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)

Spec-Kit Integration:

• Run /speckit.specify → Create detailed spec
• Run /speckit.plan → Plan implementation
• Run /speckit.tasks → Generate task list
• Create parent issue with tasks
• Use this skill to create sub-issues
• Run /speckit.implement on individual sub-issues

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.