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:
| 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 each component or subsystem in the plan, fill a failure mode table:
| 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 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?
7. What's Missing
Things the plan does not address that it should:
- Monitoring and observability (metrics, logs, alerts, dashboards)
- Error recovery paths beyond the first retry
- Edge cases outside the stated happy path
- Security considerations (authn, authz, input validation, secrets management)
- Load and scale implications (connection pools, queue depth, storage growth)
- Operational runbooks for incident response
8. Execution Assessment
Evaluate the proposed implementation order:
- Dependency ordering — Are prerequisites built before dependents?
- Parallel work opportunities — Which tasks have no mutual dependency and can proceed simultaneously?
- Risk-first vs. value-first — Does the plan tackle the highest-risk unknowns early, or defer them?
- Prototype candidates — Which components should be spiked before committing to the full implementation?
9. Verdict
Deliver exactly one of:
| Verdict | Meaning |
|---|---|
| Ship | Plan is solid. Proceed as written. |
| Ship with changes | Viable, but specific modifications listed below are required before proceeding. |
| Rethink | Fundamental structural issues require re-planning. Itemize what must change. |
| Reject | Plan is not viable. Explain why and what alternative direction to consider. |
Include a one-paragraph rationale for the verdict.
Compressed Review (Small Changes)
For small-scope changes (single file, ~100 lines), deliver four sections only:
- Scope — What the change does and its boundaries.
- Risks — Failure modes and blast radius (brief table).
- Missing — Gaps worth addressing even at this scale.
- Verdict — Ship / Ship with changes / Rethink / Reject.
Interaction Protocol
- Use
AskUserQuestionone issue at a time. Never batch multiple questions into a single prompt. - For HIGH-severity findings, surface them immediately and ask whether to continue or pause for discussion before proceeding to the next section.
- This skill is read-only. It does not create, modify, or delete any files.
- Use ASCII diagrams for data flow and component relationships where they clarify failure propagation or integration topology.
Output Format
Structured review document with:
- Numbered sections matching the sequence above
- Severity tags on every finding:
[HIGH],[MEDIUM],[LOW] - Summary table of all findings at the end, grouped by severity
- Final verdict with rationale