plan-review

Load the visual-explainer skill, then generate a comprehensive visual plan review as a self-contained HTML page, comparing the current codebase against a proposed implementation plan.

Authoring contract. Prefer the MDX/React pipeline after the plan/code fact-gathering checkpoint. Write the editable review as .mdx by default, or .tsx when the report needs custom interaction, generated SVG logic, or local state. Use shared components from visual-explainer-mdx/components.tsx, then export the generated standalone HTML with:

npm run ve:export -- <source.mdx> --out ~/.agent/diagrams/<slug>-plan-review.html

The generated HTML is the artifact, not the source of truth. Revise the MDX/TSX source when facts change or point-and-click feedback arrives, then re-export.

Clarify. This is a Tier 1 command per ./references/clarify.md. If the plan path and audience are clear from the request + context, generate directly. If the plan could be interpreted multiple ways, ask 1 clarifying question before writing HTML. Bypass with --no-ask.

Follow the visual-explainer skill workflow. Read the reference template, CSS patterns, and mermaid theming references before generating. Use a blueprint/editorial aesthetic with current-state vs. planned-state panels, but vary fonts and palette from previous diagrams.

Inputs:

• Plan file: $1 (path to a markdown plan, spec, or RFC document)
• Codebase: $2 if provided, otherwise the current working directory

Data gathering phase — read and cross-reference these before generating:

1. Read the plan file in full. Extract:

   • The problem statement and motivation
   • Each proposed change (files to modify, new files, deletions)
   • Rejected alternatives and their reasoning
   • Any explicit scope boundaries or non-goals

2. Read every file the plan references. For each file mentioned in the plan, read the current version in full. Also read files that import or depend on those files — the plan may not mention all ripple effects.

3. Map the blast radius. From the codebase, identify:

   • What imports/requires the files being changed (grep for import paths)
   • What tests exist for the affected files (look for corresponding .test.* / .spec.* files)
   • Config files, types, or schemas that might need updates
   • Public API surface that callers depend on

4. Cross-reference plan vs. code. For each change the plan proposes, verify:

   • Does the file/function/type the plan references actually exist in the current code?
   • Does the plan's description of current behavior match what the code actually does?
   • Are there implicit assumptions about code structure that don't hold?

Verification checkpoint — before generating HTML, produce a structured fact sheet of every claim you will present in the review:

• Every quantitative figure: file counts, estimated lines, function counts, test counts
• Every function, type, and module name you will reference from both the plan and the codebase
• Every behavior description: what the code currently does vs. what the plan proposes
• For each, cite the source: the plan section or the file:line where you read it Verify each claim against the code and the plan. If something cannot be verified, mark it as uncertain rather than stating it as fact. This fact sheet is your source of truth during HTML generation — do not deviate from it.

Diagram structure — the page should include:

1. Plan summary — lead with the intuition: what problem does this plan solve, and what's the core insight behind the approach? Then the scope: how many files touched, estimated scale of changes, new modules or tests planned. A reader who only sees this section should understand the plan's essence. Visual treatment: this is the visual anchor — use hero depth (larger type 20-24px, subtle accent-tinted background, more padding than other sections).

2. Impact dashboard — files to modify, files to create, files to delete, estimated lines added/removed, new test files planned, dependencies affected. Include a completeness indicator: whether the plan covers tests (green/red), docs updates (green/yellow/red), and migration/rollback (green/grey for N/A).