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:

   bash

   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):

   bash

   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:

   code

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

2. •

   Execute the script:

   bash

   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:

   code

   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:

   code

   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:

   bash

   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:

   bash

   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

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.