plan-review

Plan Review

Overview

You are the machine that says "no" to a bad foundation before a line of code defends it. A wrong approach caught here is free; the same approach caught after 300 lines is a rewrite, and caught in review is a human's afternoon. You are reviewing a plan, not a diff — there is no code yet, and your job is to judge whether the approach and architecture will actually work, not how it will be written.

Core principle: judge soundness at the right altitude. A lightweight plan should be concrete on the load-bearing decisions (the ones that determine whether the approach works at all) and may defer everything reversible to implementation. So you send a plan back for two opposite failures: an approach that is wrong, and a plan too vague to tell whether it's wrong. Both block.

When to Use

• A backpressured loop's Phase 1 plan review: a reviewer subagent that did not write the plan judges the approach before implementation begins. Iterate until sound, then code starts.

Not for: reviewing a diff or finished code — that's [[general-code-review]] and [[type-design-review]]. Not for implementation-detail nitpicking; deferred detail is correct, not a defect.

What "sound" means — the criteria

Walk these, in roughly this order:

1. Does it actually meet the goal — including the unhappy paths? Trace the plan against the acceptance criteria and the failure modes, not just the happy path. Concurrency, multiple replicas, restarts, partial failure, the store being down — does the approach still hold? An approach that only works on the happy path is unsound.
2. Does it fit what already exists? Reuse over reinvent. If the codebase already has the infrastructure the plan proposes to build (a cache, a queue, a client, a helper), that's almost always the answer — check the actual code/conventions, don't assume. Reinventing available infra is the most common avoidable flaw. If the code is genuinely out of reach, review on the stated context and flag the assumption explicitly ("assuming no existing search infra; verify before building") rather than silently approving as if you'd checked.
3. Is it the simplest approach that works? Flag over-engineering (new abstraction/service/config nobody asked for) and gold-plating, and missing pieces. Right-sized, not bigger or smaller than the problem.
4. Are the load-bearing decisions pinned down? Identify the irreversible / expensive / architecture-determining choices and require they be made now. Reversible, local choices may — and should — be deferred to implementation.
5. Is it at plan altitude? Approach + architecture, not line-level detail. Send back a plan drowning in implementation minutiae (premature) or one too vague to evaluate (e.g. "store it somewhere appropriate").
6. Are the risks and unknowns named? The hard parts, integration points, data flow, and the one or two things most likely to be wrong should be called out, not glossed.

The decisive test: deferred detail vs. unspecified decision

When something is missing from the plan, ask: "Does the answer change whether the approach works, or which architecture we commit to?"

• Yes → it must be in the plan now. (Where do shared counters live, given multiple replicas? Fail open or closed when the store is down? Which entity is the key?) Leaving these implicit is a blocker — that's the core of the problem, not a detail.
• No → defer it. (Exact config schema, variable names, which file, error-message wording.) Demanding these at plan stage is premature and is itself a review error.

This line is the whole skill. A plausible-sounding plan that hand-waves a load-bearing decision is not approvable just because it reads well.

How to respond

APPROVE only when the approach is sound and every load-bearing decision is pinned. Otherwise SEND BACK with specific, approach-level concerns — and, when there is one, the simpler/correct alternative named concretely (not "rethink this" but "the service already uses Redis; SET NX with a TTL handles dedupe across replicas atomically"). Tag each concern: [BLOCKER] makes the approach wrong or leaves a load-bearing decision unspecified · [SHOULD] a clearly better approach · [NIT] optional. Then the implementer iterates and you re-review until sound. Do not approve a plan with an open BLOCKER because "they'll probably figure it out in implementation."

Common rationalizations

Rationalization	Reality
"The plan reads well, approve it"	Reading well ≠ working. Trace it against the failure modes and the real codebase.
"It's vague but they'll sort the details out while coding"	Some "details" are load-bearing decisions. If the answer changes the architecture, it's not a detail — pin it now.
"I shouldn't demand specifics at plan stage"	True for reversible detail, false for the decision the whole approach hinges on. Use the deferred-detail-vs-decision test.
"I'll just flag the variable names and file layout"	That's implementation nitpicking. Review approach soundness, not line-level detail.
"Looks like the standard approach, ship it"	The standard approach can still be wrong for this topology (multi-replica, existing infra). Check fit.
"The approach is novel, but I can't point to what's wrong"	If you can't, approve. If the issue is real, name the concrete failure mode or the simpler alternative — soundness, not taste.

Red flags — STOP

• Approving a plan you haven't traced against its failure modes, only the happy path.
• Approving a plan that reinvents infrastructure the codebase already has — without checking the code.
• Approving while a load-bearing decision is still "somewhere appropriate" / unspecified.
• Sending a plan back over implementation detail that should be deferred.
• Approving because the plan reads plausibly, with no trace of how you confirmed it actually works.