/plan-review

name: plan-review
description: 'Pre-implementation plan audit stress-testing scope, assumptions, risks, and failure modes before code is written. Triggers on: "review this plan", "is this plan solid", "what am I missing", "challenge my assumptions", "stress-test this", "/plan-review".'
metadata:
  version: 1.1.0
  category: review
  tags: [plan-audit, scope, risk-assessment, assumptions]
  difficulty: intermediate

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

Use the requested lens: Product, Engineering, or Combined. When none is specified, use Combined without a configuration question. Resolve facts from the plan and repository; ask only for a material decision the evidence cannot settle.

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 and its authoritative project goal. Summarize the intended user workflow, the next useful outcome, non-goals and constraints in 2–3 sentences. Identify a mismatch between project value and technically coherent milestones before reviewing implementation detail. Do not pause for confirmation unless an unresolved contradiction changes the outcome or safety.

2. Assumption Challenge

Extract material assumptions that could change the next outcome or its safety. For each one:

| Assumption | If wrong? | Supporting evidence | What falsifies it? | | ---------- | --------- | ------------------- | ------------------ |

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 components on the next delivery path, identify demonstrated failure risks:

| Component | Failure Mode | Blast Radius | Recovery Strategy | | --------- | ------------ | ------------ | ----------------- |

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 current failures explicit and recoverable where required? Do not prescribe a registry or retry framework without a consumer.
• **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** — Does the design meet evidenced workload and latency constraints? Hypothetical 10x capacity is not a gate without a source requirement.
• **Test strategy adequacy** — Do focused tests and an observed interaction cover the promised behavior and affected contracts? Separate fast local/PR feedback, integration-candidate checks and broad mainline/release coverage.

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)

• **Necessary now vs. eventually useful** — Does each milestone advance the next useful project outcome? For prerequisites and architectural expansion, name the consumer and concrete cost or risk of deferral.
• **Deferral candidates** — Defer optional capability with a revisit condition. Preserve correctness, security, data integrity and expensive-to-reverse constraints of the current capability.
• **Changeability vs. speculative extensibility** — Favor clear boundaries and affordable refactoring over unused frameworks, providers or deployment machinery.
• **Planning horizon** — Detail actionable milestones; keep distant outcomes provisional. Missing distant execution prompts are not defects.
• **Delivery cost** — Prefer one cohesive PR unless a split improves review or safe integration; examine stack depth and repeated CI/review waits.

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?

7. What's Missing

Report a missing element only when a source requirement or concrete failing scenario makes it necessary for the current outcome. Consider security, data integrity, recovery, workload and operational needs at that boundary; do not turn this list into mandatory dashboards, runbooks, retries, benchmarks or extra qualification. Put optional improvements under non-blocking follow-ups, or omit them.

8. Execution Assessment