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

Environment Variables:

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

Token Scopes:
- GITHUB_TOKEN - Requires repo scope for issue operations
- Must have write access to the repository
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:

Extract issue number from user request:

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

Execute the script:

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

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

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:

Recognize the request:

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

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

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:

Execute in dry-run mode:

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

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

Auto-detects repository - Uses git context to determine owner/repo
Fetches parent issue - Retrieves issue title, body, labels, assignees via GraphQL
Parses task lists - Supports multiple formats (see Parsing Patterns)
Shows preview - Displays proposed sub-issues with inherited metadata
Confirms with user - Waits for confirmation before creating
Creates sub-issues - Uses GraphQL createIssue mutation with parentIssueId
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:

Use --dry-run first to preview what will be parsed
Add a dedicated ## Tasks or ## Implementation Tasks section
Or use --section "Phase Tasks" to target specific section
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:

Preview first: --dry-run to see what's being parsed
Add task section: Restructure issue with ## Tasks header
Target specific section: Use --section "Implementation Tasks"
Strict mode: Use --checkbox-only to only parse - [ ] items
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:

Check section header: Ensure tasks are under ## Tasks, ## Sub-Issues, or similar
Specify section explicitly: Use --section "Your Custom Header"
Disable filtering: Use --all-bullets to parse all bullets (legacy behavior)
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:

Run --dry-run to review what's being parsed
Restructure issue to have clear task section
Use --section or --checkbox-only for stricter parsing
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

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

Integration with Existing Workflow

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

Standard Workflow:

Create parent issue (existing)
NEW: Use this skill to break down into sub-issues
Create branch for sub-issue work (existing)
Development (existing)
Create PR (existing)
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.