/issue-plan-review

description: Read a GitHub issue and all comments, review the implementation plan, independently assess each finding, and present findings
argument-hint: <issue-number> [context]
allowed-tools: Bash, Read, Grep, Glob, Task, TaskCreate, TaskUpdate, AskUserQuestion

Issue Plan Review

You are reviewing the implementation plan for a GitHub issue. Your goal is to read the issue and all comments, independently assess the plan, and present your findings.

**User input:** $ARGUMENTS

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

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 review.

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 5 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 and locate plan | Reading the issue | | Step 2 | Step 2: Explore the codebase | Exploring the codebase | | Step 3 | Step 3: Review the plan | Reviewing the plan | | Step 4 | Step 4: Run independent assessment | Running independent assessment | | Step 5 | Step 5: Present findings and execute decision | Presenting findings |

Mark Step 0 complete.

Step 1: Read the issue and locate plan

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

Understand:

• The original problem statement and requirements
• The implementation plan (typically posted as a comment)
• Any discussion, decisions, or clarifications in the comment thread

Locate the implementation plan comment by searching all issue comments for the `<!-- mach10-plan -->` HTML marker. If multiple comments contain the marker, use the last one (the most recent revision). If no comment contains the marker, fall back to identifying the most recent substantive comment that contains a staged implementation plan. If no plan exists at all, inform the user and suggest running `/mach10:issue-plan <issue-number>` first. Leave Step 1 as `in_progress` and stop -- do not continue to Step 2.

On success, 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 a complete plan should satisfy.

Record these as **project review criteria** -- they will serve as benchmarks when assessing the plan in Step 3.

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

2b. Explore

Launch 6 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 of plan verification. All lenses are required -- Step 3 always evaluates risks, testing, and alternatives, so their corresponding evidence-gathering lenses must always run:

• **Files referenced in the plan**: Trace through each file referenced in the plan comprehensively, confirming they exist, checking their current state, and verifying the plan's characterization of their structure, responsibilities, and integration points is accurate.
• **Architecture and patterns**: Trace through the relevant architecture comprehensively, validating that the plan aligns with existing codebase conventions, abstractions, data flow, and design decisions.
• **Gaps**: Trace through code adjacent to the plan's scope comprehensively, looking for constraints, dependencies, cross-cutting concerns, or affected areas the plan may have missed.
• **Risks and pitfalls**: Investigate what could go wrong with the plan's proposed approach. Look for failure modes, boundary conditions, implicit assumptions, or architectural concerns in the areas the plan modifies.
• **Alternative approaches**: Look for codebase evidence that a different approach could achieve the same goals. Identify existing patterns, abstractions, or design decisions that suggest a simpler, more idiomatic, or more robust solution than what the plan proposes.
• **Test infrastructure**: Examine the project's test suite -- frameworks, patterns, test organization, coverage approach, and any test utilities or fixtures relevant to the areas the plan modifies.

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 focus review on the user's areas of concern.

If project review criteria were recorded in Step 2a, include them in each agent's context so exploration can verify whether the plan covers the relevant project layers and testing infrastructure.

Each agent should return a list of key files and observations. After agents com