github-planner

name	github-planner
description	Fetch a GitHub issue and create a detailed implementation plan. Use when given a GitHub issue URL or number to analyze the issue, explore relevant codebase areas, and produce a step-by-step implementation plan with file changes, architecture considerations, and risk assessment.
user_invocable	true

GITHUB ISSUE IMPLEMENTATION PLANNER

Fetch a GitHub issue, analyze its requirements, explore the relevant codebase, and produce a comprehensive implementation plan.

When to use: Execute /plan-issue with a GitHub issue URL or number to generate an implementation plan before starting work.

Step 1: Fetch Issue

Run the fetch script to retrieve issue details:

uv run .claude/skills/github-planner/scripts/fetch_issue.py <issue_url_or_number>

Accepts:

• Full URL: https://github.com/owner/repo/issues/123
• Short URL: owner/repo#123
• Issue number (uses current repo): 123 or #123

The script outputs structured JSON with title, body, labels, comments, and metadata.

Step 2: Analyze Issue

Parse the fetched issue content and identify:

1. Problem statement - What needs to be solved
2. Proposed solution - If described in the issue
3. Acceptance criteria - Explicit or inferred requirements
4. Scope boundaries - What is and isn't included

Step 3: Explore Codebase

Based on the analysis, explore relevant parts of the codebase:

1. Use Glob/Grep to find files related to the issue's domain
2. Read key files to understand current architecture
3. Identify integration points and dependencies
4. Check for existing patterns that the implementation should follow
5. Reference CLAUDE.md for project architecture and conventions

Step 4: Generate Implementation Plan

Write the plan to private-docs/plans/<issue-number>-<slug>.md using the template:

uv run .claude/skills/github-planner/scripts/create_plan.py \
  --issue <number> \
  --title "<issue-title-slug>"

Fill the generated template with:

• Overview: Issue summary and goals
• Architecture Analysis: How changes fit into existing architecture
• Implementation Steps: Ordered tasks with specific file changes
• Files to Modify/Create: Exhaustive list with descriptions
• Risk Assessment: Potential issues, edge cases, breaking changes
• Testing Strategy: How to verify the implementation

Step 5: Present Plan

After writing the plan file, present a concise summary to the user:

1. Key architectural decisions
2. Number of files affected
3. Implementation order
4. Any open questions or ambiguities from the issue

• Language: All plans MUST be written in English (per CLAUDE.md)
• Specificity: Reference exact file paths and function names
• Actionable: Each step should be independently implementable
• Architecture-aware: Respect existing patterns from CLAUDE.md
• Scope-bounded: Do not plan beyond what the issue requests

• Plan template - Markdown template for implementation plans