Plan Review

Thorough review of a plan before a single line of code is written. Every blocker caught here saves a debugging session later.

When to Use

• User pastes a plan and asks for review
• User says "review my plan", "find gaps", "anything missing?", "is this solid?"
• User shares a path to a .plan.md file (often in ~/.cursor/plans/)
• User asks "is this ready to implement?" or "anything I haven't thought of?"
• After write-plan produces a draft and before implementation starts

Do not use this skill when:

• Implementation has already started — use gap-check instead
• The user wants help writing a plan — use write-plan
• The user wants strategic brainstorming — use ce-brainstorm

Preflight — classify the plan

Before reviewing, identify which kind of plan this is. The 12-gap checklist in Phase 3 is web-app-biased and maps poorly onto other plan types. Classify first:

• Web/app feature plan — touches API routes, DB, UI, shared packages. Default case. Use the full Phase 3 12-gap list.
• Tooling / infra / shell / docs / skill plan — touches install scripts, CI, documentation, local dev tooling, or skill files. Skip most of Phase 3 and use the "Infra plan track" below.
• Research / exploration plan — open-ended, no single deliverable. Convert to a working doc rather than reviewing as a plan.
• Mixed — run both Phase 3 tracks for the relevant sections.

State the classification as the first line of your review output so the user knows which track you used.

Steps

Phase 1 — Read the plan thoroughly

If a file path is given, read it first. If the plan is pasted inline, read it in full before commenting on any part. Do not skim and jump to the first flag.

Capture:

• Goal — what outcome does this plan deliver?
• Scope — what's in and what's out?
• Todos — the numbered checklist of work items, if present
• Assumptions — what the plan takes as given
• Dependencies — other services, packages, features the plan depends on

If any of these are missing or ambiguous, they're your first flags.

Phase 2 — Cross-reference with the codebase

The plan exists in the context of a real codebase. Verify the plan's claims against reality:

1. Files exist. Every file referenced in the plan — does it exist at that path?
2. Types exist. If the plan references shared types, interfaces, or enums, grep for them. If they're new, the plan must include adding them.
3. Patterns match. Does the plan's approach match how similar things are already done? A plan that introduces a new auth pattern when five routes already use a working one is a yellow flag.
4. Dependencies installed. If the plan uses a new library, is it in package.json? If not, the plan must include installing it.
5. Database schema aligns. If the plan touches DB, check the current schema. New fields? Migration plan included? Backfills needed?
6. Envars documented. If the plan needs new secrets/config, is provisioning part of the plan?

Any mismatch between plan and codebase is a finding.

Phase 3 — Check for common gaps (use the track from Preflight)

Web/app feature plan track — 12-gap checklist

Flag each as Present / Partial / Missing / N/A (with one-line justification):

1. Error handling. What happens when each step fails? Network errors, validation errors, auth failures, timeout, partial state.
2. Rollback path. If the feature ships and goes wrong, what's the rollback?
3. Backwards compatibility. Does this break existing users, data, or API contracts?
4. Race conditions. Any async operations that could interleave badly?
5. Authorization. Who can call each new endpoint / access each new route?
6. Input validation at boundaries. User input, external API responses, URL params — where are they validated?
7. Observability. What's logged? What metrics are emitted? How will you debug this at 2am?
8. Migration + backfill. For DB changes: apply, backfill, deploy, verify. Is the order safe for concurrent writes?
9. Cross-service contract. Changes touching multiple services — shared packages versioned? Deploy order coordinated?
10. Analytics events. New user actions — are new analytics events specified?
11. Tests. Strategy stated? Unit, integration, e2e? Happy-path-only?
12. Rate limiting / abuse. New public-facing endpoints — rate limited? Abuse paths considered?

Infra / tooling / shell / docs plan track — 8-gap checklist

For plans that target install scripts, CI, local tooling, or documentation:

1. Idempotency. Can the plan's steps be re-run safely without corrupting state? (Installers, migrations, backfills.)
2. Destructive operations. Does any step delete, overwrite, or force-replace files, symlinks, remote refs, or DB rows? Is each destructive step explicit, reversible, and gated on confirmation/--force?
3. Dry-run / preview. Can the user see what would happen before it happens? Default behavior should be safe.
4. Uninstall / rollback. Is there a way to undo what the plan installs?
5. Cross-machine portability. Does the plan assume a specific path, shell, OS, or tool version? What breaks on Linux vs macOS vs WSL?
6. Secret handling. Any step that touches tokens, env vars, or credentials — are they read from secure sources, never logged, never committed?
7. Failure modes. What happens when a step fails mid-way? Can the user resume, or do they have to start over?
8. Docs + examples. Is the user-facing surface (README, --help, error messages) updated alongside the code?

Research / exploration plan track

This is not a review target. Flag: "This plan is exploratory. Convert to a working doc or a concrete scoped plan before review."

Mixed plan track

Run both #1 and #2 tracks for the relevant sections. Call out which track applies to which section in the output.

Phase 4 — Produce the review

Use this exact structure:

# Plan Review — {{plan name}}

## Blockers (fix before starting)
Will cause broken implementation. Numbered.
1. [File/area] — [concrete issue]
   - Option A (recommended): [fix] — [why]
   - Option B: [alternative]
   - Option C: [do nothing — consequence]

## High-Priority Gaps (should fix)
Will cause production bugs. Numbered.

## Low-Priority Gaps (nice to have)
Edge cases, UX polish, minor optimizations.

## Questions for You (need clarification)
Ambiguous requirements or decisions that affect direction.

## Strengths (keep these)
Optional. Only include if there are genuine strengths worth calling out.

## Verdict
**Go / No-go / Needs revision** — state it plainly, one paragraph explaining the call.

Phase 5 — Do not implement

Stop after Phase 4. Implementation happens after the user accepts the findings.

Output Format

See Phase 4. Rules:

• Number every issue (1, 2, 3...). Letter every option within an issue (A, B, C).
• Option A is always the recommendation with a stated reason. Option C can be "do nothing" with its consequence.
• Concrete file/line references wherever possible: src/app/api/users/route.ts:42
• Never "looks good" unless the plan genuinely has zero findings. If it does, say so confidently.

Rules

1. Review only. Do not implement. Users need the list before code changes.
2. Honest about severity. Don't file every nitpick as a Blocker. Don't demote a real blocker to be nice.
3. Cross-reference the codebase when possible. Reviews that skip Phase 2 catch maybe 30% of real issues. When the target doesn't exist yet (new repo, pre-creation plan), state that upfront and skip Phase 2 explicitly — do not fabricate paths.
4. Options when there's a real choice. Non-trivial findings with multiple valid solutions get 2–3 options (A recommended, B/C alternatives). Single-fix bugs get one fix — do not pad with fake alternatives.
5. Ask before guessing. If context is missing, ask. Don't manufacture requirements.
6. Strengths section is optional. Only include genuine strengths. Empty praise is noise.
7. Final verdict is three-way. "Go" (ready to implement), "No-go" (fundamentally unsound, rewrite required), or "Needs revision" (specific blockers listed, re-review after fix). Not "it depends".
8. In subagent / headless mode, emit the report and stop. Do not prompt for action — the calling agent or downstream orchestrator handles next steps. Mention applicable follow-ups as a "Next steps" section rather than a question.

Worked Example — Output

# Plan Review — Add team invites to onboarding

## Blockers (fix before starting)

1. **No rollback path for partially-accepted invites.** Plan says "insert row,
   send email, return." If email fails after insert, user sees success with no
   email and no retry path.
   - **(A) Recommended:** wrap in transaction that rolls back on email failure.
     File: `src/api/invites/create.ts`
   - (B) Fire-and-forget via queue; mark row `pending_email` on queue failure.
   - (C) Accept ~0.5% silent failures.

2. **Plan references `src/lib/auth/canInvite.ts` — file doesn't exist.**
   Actual location is `src/auth/permissions.ts` exporting `canInviteToOrg`.
   - **(A) Recommended:** update plan to use real path.
   - (B) Create new helper at the plan's specified path.

## High-Priority Gaps (should fix)

3. **No rate limit on invite endpoint.** Authenticated user could send
   10,000 invites per minute.
   - **(A) Recommended:** apply existing `rateLimit` middleware at
     `src/middleware/rate-limit.ts:15`, 50/hr/user.

4. **Race condition on "invite already pending" check.** Concurrent requests
   can both pass uniqueness check and both insert.
   - **(A) Recommended:** DB unique index on `(org_id, email)`, handle
     UNIQUE_VIOLATION as "already invited".

## Low-Priority Gaps

5. **No analytics events** for invite sent/accepted/rejected. Growth team
   will ask within a week.

## Questions for You

6. **Expiration policy?** Do invites expire? If so, after how long?
7. **Revocation?** Can an admin revoke a pending invite?

## Strengths

- Includes email template content, not just a reference — saves back-and-forth.
- Uses existing `Invite` model instead of creating a new one.
- Lists three failure modes upfront.

## Verdict

**Needs revision.** Two blockers (1, 2) must be addressed. Once those are
resolved and questions 6–7 are answered, this is close to ready. Expect one
more review pass after revision.

Pipeline Position

write-plan → [plan-review] → (implement) → gap-check → simplify → pre-ship → (deploy) → pr-triage

Plan-review is the gate between planning and implementation. Go verdict = hand the plan to an implementer (human or agent) with confidence.