Plan Review

Plan Review Skill

Purpose

Execute a structured pre-implementation audit of a technical plan, proposal, or design document. The goal is to surface risks, bad assumptions, missing pieces, and scope problems before any code is written — when course corrections are cheapest.

This skill is read-only. It never modifies code. It produces a severity-tagged review document with a final ship/rethink/reject verdict.

Step 0 — Mode Selection

Ask the user a single question via AskUserQuestion:

Which review lens? (1) Product — scope, user impact, business alignment. (2) Engineering — architecture, failure modes, test strategy, performance. (3) Combined (default) — both lenses integrated.

Accept the answer and proceed. Do not ask follow-up configuration questions.

Also assess scope size from the plan:

• Small change (single file, ~100 lines or fewer): deliver a compressed 4-section review — Scope, Risks, Missing, Verdict. Skip the full multi-section template.
• Standard change: execute the full review sequence below.

Full Review Sequence

1. Plan Comprehension

Read the plan end-to-end. Produce a 2–3 sentence summary confirming understanding. Explicitly list:

• Stated goals — what the plan claims to achieve.
• Non-goals — what is explicitly out of scope.
• Constraints — budget, timeline, compatibility, team size, or technology constraints mentioned or implied.

If the summary is wrong, the user corrects it here before the rest of the review proceeds on a false foundation.

2. Assumption Challenge

Extract every implicit assumption. For each one:

Common assumption categories to probe:

• Data availability and shape
• Third-party API stability and rate limits
• Team familiarity with chosen tools
• Performance characteristics of dependencies
• Backward compatibility requirements
• Deployment environment capabilities

3. Risk & Failure Mapping

For each component or subsystem in the plan, fill a failure mode table:

Additionally identify data flow shadow paths — side effects, async callbacks, event propagation, or cache invalidation chains that are not on the happy path but will execute in production.

Use ASCII diagrams to illustrate non-obvious data flow or failure propagation where the plan involves three or more interacting components.

4. Component-by-Component Review (Engineering Lens)

For each major component, assess:

• Error handling strategy — Are errors classified and routed through a registry, or silently swallowed by catch-all handlers?
• Data integrity invariants — What invariants must hold? How are they enforced? What happens when they break?
• Concurrency and race conditions — Shared state, lock ordering, optimistic vs. pessimistic strategies, idempotency guarantees.
• Performance under load — Expected throughput, latency budget, resource consumption at 10x current scale.
• Test strategy adequacy — Unit, integration, and end-to-end coverage for the component. What is untestable and why?

This section is language- and framework-agnostic. Reference references/project-detection.md for framework-aware examples when the user's stack is known.

Skip this section when running product-lens-only mode.

5. Scope & Priority Assessment (Product Lens)

• Needed vs. nice-to-have — Which features are load-bearing for the stated goals? Which are speculative?
• Deferral candidates — What can ship in a follow-up without increasing risk?
• Over-engineering indicators — Abstractions, configurability, or extensibility that no current requirement demands.
• User-facing impact — Does the complexity produce proportional user value?

Skip this section when running engineering-lens-only mode.

6. Integration Review

How components connect to each other and to the outside world:

• API contracts — Request/response shapes, versioning, error codes between modules.
• State management across boundaries — Who owns state? How is it synchronized? What happens during partial failure?
• Migration and deployment ordering — Which components must deploy first? Are there intermediate states where the system is inconsistent?
• Rollback compatibility — Can each deployment step be reversed independently? What data is irreversible?