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.

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

3. Current architecture, Mermaid diagram of how the affected subsystem works today. Focus only on the parts the plan touches, don't diagram the entire codebase. Show the data flow, dependencies, and call paths that will change. Wrap in .mermaid-wrap with zoom controls (+/−/reset/expand buttons), Ctrl/Cmd+scroll zoom, click-and-drag panning, and click-to-expand (opens diagram full-size in new tab). See css-patterns.md "Mermaid Zoom Controls" for the full pattern including the openMermaidInNewTab() function. Visual treatment: use matching Mermaid layout direction and node names as section 4 so the visual diff is obvious.

4. Planned architecture, Mermaid diagram of how the subsystem will work after the plan is implemented. Use the same node names and layout direction as the current architecture diagram so the differences are visually obvious. Same zoom controls and click-to-expand as section 3. Highlight new nodes with a glow or accent border, removed nodes with strikethrough or reduced opacity, changed edges with a different stroke color.