By the time you are reviewing the diff, the argument is already expensive. The agent built the feature. There are four hundred lines across nine files, tests are green, and now you notice the whole thing assumed coupons stack when the rule is that they never do. Fixing it means unwinding work that already exists, re-running the agent, and reviewing it all again.
You could have caught that in the spec, before a single line was written, in the time it takes to read one page. Reviewing the spec instead of only the diff is the highest-leverage review available in spec-driven development, and almost nobody does it, because the habit of software review is bound to code.
The cost of a mistake climbs with every step
A misunderstanding is cheapest to fix at the moment it is still just a sentence. In the spec, a wrong assumption is one line you cross out and rewrite. After the agent builds, that same wrong assumption is spread across the implementation, the tests that now encode it, and any code that already depends on it. The mistake did not get worse. It got more expensive to remove, because it grew a structure around itself.
Agents make this curve steeper, not gentler. A human who half-understood a spec would slow down, hesitate, and ask. An agent does not hesitate. It takes your ambiguous instruction and confidently generates a complete, plausible, wrong implementation at full speed, then writes tests that lock the misunderstanding in. The faster the builder, the more it costs to review only at the end, because there is simply more built-out wrongness to unwind.
Reviewing the spec is how you catch the mistake while it is still one sentence. This is what makes it cheap. You are not arguing with code. You are correcting intent before intent has been turned into anything.
What a spec review actually looks for
A spec review is not a proofread. You are not checking grammar. You are checking whether the contract is the right contract, and there are a few specific failure modes worth hunting for.
Ambiguity an agent will resolve wrongly. Read every sentence and ask how a literal-minded, overconfident builder could interpret it. “Validate the input” against what? “Handle errors” how? Anywhere the spec leaves a decision implicit, the agent will make that decision for you, and you will meet its choice in the diff. The spec review is where you close those gaps while closing them is free.
Missing boundaries. What must stay true that the spec forgot to say? The invariants an agent is most likely to break are the ones nobody wrote down, because the agent cannot protect a constraint it was never told about. A spec review is largely a hunt for the unstated “and don’t break this.”
Criteria you could not actually check. Every acceptance criterion should be one you can imagine verifying against a real result. “Works correctly” is not checkable. This is the moment to turn soft language into acceptance criteria an agent can verify, because a criterion you cannot check in the spec is a criterion you cannot enforce in the code either.
The wrong thing, well specified. The most expensive miss. The spec is clear, complete, and describes a feature nobody needed. No diff review catches this, because the code will faithfully match the spec. Only reading the spec as a statement of intent, and asking whether the intent is right, catches it.
A useful habit is to read the spec twice with two different questions. The first pass asks “will an agent build the wrong thing from this?” and hunts for ambiguity and missing boundaries. The second pass asks “is this the right thing to build at all?” and ignores the wording entirely to interrogate the intent. These are genuinely different reads, and most people only do the first, which is why the clear-but-wrong spec sails through. The whole point of moving the review this early is that both questions are still cheap to answer. Change your mind about the intent here and it costs a rewrite of one page. Change it after the diff and it costs the diff.
It is the release valve for review fatigue
There is a second reason to move the review earlier, and it is about your own attention. When agents produce code faster than anyone can read it, review becomes the bottleneck and reviewers burn out. This is review fatigue, and throwing more diff-reading at it does not help, because the diffs keep arriving faster than you can absorb them.
Spec review attacks the volume upstream. A page of spec takes minutes to read and determines hundreds of lines of code. Catching a problem there means the bad diff never gets generated, never gets reviewed, and never gets re-reviewed after the fix. You are not reading less carefully. You are reading the artifact where careful reading pays the most and the volume is smallest.
It also changes what the diff review is for. When the spec was reviewed and agreed first, reviewing the code you didn’t write becomes a check of “does this match the contract?” rather than an open-ended hunt through unfamiliar code for problems you have not defined yet. Scope first, diff last. The spec review is the scope.
This reordering is also what makes the later review survivable at all. A diff review with no agreed spec behind it is an infinite task, because there is no defined standard of done, so you keep reading until you run out of energy rather than until you run out of contract. A diff review against a reviewed spec is a finite task with a clear stopping point: the code either satisfies the criteria or it does not. Moving the review earlier does not just catch mistakes sooner. It gives the whole review process a floor and a ceiling.
Where PaellaDoc fits
Putting the review before the build is the workflow PaellaDoc is shaped around. A change starts as a spec you can read and correct while it is still cheap to correct, with its intent, boundaries, and acceptance criteria in front of you before the agent runs. Because that reviewed spec stays connected to the code and the evidence, the later diff review has something to check against, and the spec you agreed to is the standard the result is measured by rather than a document nobody reopened.
The cheapest review you will ever do is the one that happens before anything exists to review. A page of intent, read carefully, decides the shape of everything the agent builds next. Skip it and you pay for every misunderstanding at diff prices, over and over, at agent speed.
FAQ
Isn’t reviewing the spec just extra work on top of reviewing the code? No, it moves the work earlier and makes it smaller. A page of spec decides hundreds of lines of code. Catching a mistake in the spec means the wrong diff is never generated or reviewed at all, so the total review effort goes down.
What am I looking for in a spec review? Ambiguity an agent will resolve wrongly, boundaries the spec forgot to state, acceptance criteria you could not actually verify, and the case where the spec is clear but describes the wrong feature. The last one is the only place it gets caught.
Does spec review replace code review? No. It changes what code review is for. With the spec reviewed and agreed first, the diff review becomes a check against a known contract instead of an open-ended search for undefined problems in unfamiliar code.