/issue-plan

description: Read a GitHub issue, analyze the codebase, and create a staged implementation plan
argument-hint: <issue-number> [context]
allowed-tools: Bash, Read, Grep, Glob, Task, TaskCreate, TaskUpdate, AskUserQuestion

Issue Plan

You are creating a staged implementation plan for a GitHub issue. Your goal is to deeply understand the issue, explore the relevant codebase, and produce a plan where each stage can be implemented within a single Claude Code CLI session.

**User input:** $ARGUMENTS

**Note:** This command performs best with an Opus-class model. On Sonnet or Haiku, results may be shallower.

Guardrails

This command is strictly for **planning**. Do NOT:

• Use `EnterPlanMode` or enter plan mode
• Implement any code changes -- no file edits, no file writes
• Attempt to execute the plan within this session

Implementation happens in separate sessions via `/mach10:issue-implement`.

Step 0: Parse input and create task list

The user's input contains:

• An **issue number** (required)
• Additional **context** or constraints (optional)

Extract the issue number from the input. If the input is ambiguous, ask the user to clarify. If context was provided, note it for use during exploration and planning.

After parsing input, create the progress-tracking task list. Create a task for Step 0 and immediately mark it in progress. Then create tasks for each of the remaining 6 steps one at a time, in step order, all starting as pending. Task list display order matches creation order, so each task must be a separate sequential call -- do not batch multiple task creations in a single message. Store each returned task ID for later use -- do not assume IDs are sequential.

| Task | Subject | activeForm | |------|---------|------------| | Step 0 | Step 0: Parse input and create task list | Parsing input | | Step 1 | Step 1: Read the issue | Reading the issue | | Step 2 | Step 2: Explore the codebase | Exploring the codebase | | Step 3 | Step 3: Ask clarifying questions | Asking clarifying questions | | Step 4 | Step 4: Design architecture | Designing architecture | | Step 5 | Step 5: Draft the plan | Drafting the plan | | Step 6 | Step 6: Post plan and create branch | Posting plan and creating branch |

Mark Step 0 complete.

Step 1: Read the issue

Mark Step 1 in progress.

Read the issue title and body:

gh issue view <issue-number>

Then read all comments (`--comments` returns only comments and silently drops the title and body, so both calls are required):

gh issue view <issue-number> --comments

Parse and understand:

• The problem statement
• Any constraints or requirements mentioned
• Prior discussion or decisions in the comments
• Acceptance criteria (if specified)

Mark Step 1 complete.

Step 2: Explore the codebase

Mark Step 2 in progress.

2a. Read Contributing Guidelines

Before launching exploration agents, look for project contribution guidelines in order of precedence:

CONTRIBUTING.md
DEVELOPMENT.md
.github/CONTRIBUTING.md

Read only the first file found; skip the rest.

If found, read the file and extract any planning-relevant guidance: expected project layers (e.g., models, migrations, API routes, services, UI, documentation), testing expectations (test frameworks, coverage requirements, test types), and any other requirements that should inform the implementation plan.

Record these as **project planning requirements** -- they will inform both the exploration focus and the plan drafting in Step 5.

If no contributing guide exists, proceed without project-specific requirements.

2b. Explore

Launch 4 exploration agents of type `feature-dev:code-explorer` in parallel by delegating to subagents. Each agent should trace through the code comprehensively and target a different aspect. All lenses are required -- Step 3 always evaluates constraints and edge cases, and Step 4 requires constraint awareness for sound architecture design, so their corresponding evidence-gathering lens must always run:

• **Similar features**: Find existing code that solves related problems. Trace through their implementation comprehensively, identifying patterns and conventions the new work should follow.
• **Architecture**: Map the architecture and abstractions for the relevant area, tracing through the code comprehensively to understand the layers, data flow, and design decisions.
• **Integration points**: Identify where new code would connect to existing systems, including extension surfaces, testing infrastructure, and cross-cutting concerns.
• **Constraints and edge cases**: Investigate constraints and edge cases that the issue does not mention but the codebase reveals. Look for boundary conditions, implicit assumptions, error paths, or environmental requirements in the affected areas.

Do not run these subagents in the background. For parallel execution, launch them in a single message instead.

If the user provided context, include it in each agent's prompt to guide exploration focus.

If project planning requirements were identified in Step 2a, include them in each agent's context so exploration covers the relevant project layers and testing infrastructure.

Each agent should return a list of 5-10 key files. After agents complete, read all identified files to build deep understanding.

Present a comprehensive summary of findings and patterns discovered.

Mark Step 2 complete.

Step 3: Ask clarifying questions

Mark Step 3 in progress.

**CRITICAL**: This is one of the most important steps. DO NOT SKIP.

Review the codebase findings from Step 2 against the issue requirements. Identify all underspecified aspects:

1. Present a clear analysis of the problem based on what you found in the codebase. 2. Identify ambiguities, underspecified scope, unstated constraints, edge cases, integration concerns, and design preferences that will affect the implementation plan. 3. **Present all questions to the user in a clear, organized list.** 4. **Wait for