GitHub Issue Planning Workflow Skill

This skill provides a comprehensive methodology for planning implementation of GitHub issues.

Planning Phases

Phase 1: Issue Intelligence

Gather all information:

# Get issue details
gh issue view {number} --json title,body,labels,milestone,comments,assignees

# Get comments
gh issue view {number} --comments

# Check related PRs
gh pr list --search "#{number}" --json number,title,state

Extract:

• •Core problem/goal
• •Acceptance criteria
• •Technical hints in description
• •Context from comments
• •Related issues referenced

Phase 2: Codebase Exploration

Systematic exploration:

1. •Find relevant files:

# Search for keywords
rg "keyword" --type ts -l

# Find component files
ls src/components/ | grep -i "feature"

1. •Understand current state:

• •Read main files involved
• •Note patterns and conventions
• •Identify extension points
• •Check test coverage

1. •Document findings:

• •File paths with line numbers
• •Current implementation details
• •Patterns to follow
• •Potential challenges

Phase 3: Clarification

Ask targeted questions:

Format:

### Question: [Topic]

**Context**: [What you discovered]

**Options**:
A) **[Option]** - [Description]
   - Pros: [Benefits]
   - Cons: [Drawbacks]

B) **[Option]** - [Description]
   - Pros: [Benefits]
   - Cons: [Drawbacks]

**Recommendation**: Option [X] because [reasoning]

Good questions:

• •Technical approach decisions
• •Scope clarifications
• •Priority of edge cases
• •UI/UX preferences

Avoid:

• •Questions answered in issue
• •Questions answerable from code
• •Yes/no questions without context

Phase 4: Plan Generation

Structure:

## Implementation Plan: #{number}

### Overview
[1-2 sentence summary of approach]

### Architecture Changes
[New components, files, APIs]

### Implementation Steps

#### Step 1: [Title] (Complexity: Low/Medium/High)
**What**: [Description]
**Files**:
- `path/to/file.ts` - [What to change]

**Key Points**:
- [Critical detail 1]
- [Pattern to follow]

**Testing**: [How to verify]

#### Step 2: [Title]
...

### Testing Strategy
- **Unit tests**: [What to test]
- **Integration tests**: [What to test]
- **Manual verification**: [Steps]

### Risks
| Risk | Impact | Mitigation |
|------|--------|------------|
| [Risk] | High/Med/Low | [Strategy] |

### Success Criteria
- [ ] [Criterion from issue]
- [ ] [Additional criterion]

Phase 5: Branch & Assignment

Create branch:

# Ensure up to date
git checkout main && git pull

# Create feature branch
git checkout -b feature/{number}-{brief-description}

# Push to remote
git push -u origin feature/{number}-{brief-description}

Update issue:

# Assign to self
gh issue edit {number} --add-assignee @me

# Add in-progress label
gh issue edit {number} --add-label "in progress"

# Add plan comment
gh issue comment {number} --body "Starting work. Plan: [brief summary]. Branch: \`feature/{number}-...\`"

Branch Naming

Format: {type}/{number}-{brief-description}

Types:

• •feature/ - New functionality
• •fix/ - Bug fixes
• •chore/ - Maintenance
• •docs/ - Documentation
• •refactor/ - Code improvements
• •test/ - Test additions

Examples:

feature/123-user-notifications
fix/456-checkout-timeout
chore/789-update-deps
docs/101-api-examples

Sanitization rules:

• •Lowercase
• •Replace spaces with hyphens
• •Remove special characters
• •Keep under 50 chars

Plan Quality Checklist

Before presenting plan:

• • Explored all relevant code
• • Identified patterns to follow
• • Steps are specific and actionable
• • Dependencies between steps noted
• • Testing strategy defined
• • Risks identified
• • Success criteria from issue included
• • Estimated complexity per step

Step Complexity Guidelines

Low Complexity:

• •Single file change
• •Clear pattern to follow
• •No new dependencies
• •Minimal testing needed

Medium Complexity:

• •Multiple related files
• •Some decisions required
• •New tests needed
• •May need clarification

High Complexity:

• •Architectural changes
• •Multiple components
• •New patterns/approaches
• •Significant testing
• •Potential risks

Integration Notes

Linking work:

# In commit messages
git commit -m "feat(#123): implement notification service"

# In PR title
[#123] Add user notifications

Auto-close keywords:

• •Fixes #123
• •Closes #123
• •Resolves #123

Reference keywords:

• •Related to #123
• •Part of #123
• •See #123