How to review AI-generated specifications without rubber-stamping them

The bottleneck moved. A year ago, writing a detailed specification was the slow part. Now an AI can produce a 1,500-line spec, plan, or ADR in minutes, and the slow part is the one thing that did not get faster: a human reading it carefully enough to trust it.

This matters because a specification is not throwaway output. Code review at least has tests, types, and a compiler pushing back. A spec has none of that. If a reviewer approves a plausible-looking spec without really reading it, the errors do not get caught at the spec stage. They get caught three weeks later, built into the thing the spec described.

So the risk with AI-generated specs is not mainly that the AI writes bad specs. Modern models write fluent, well-structured, confident prose. The risk is that fluent, well-structured, confident prose is exactly what gets rubber-stamped, and the tooling we use to review it was built for small code diffs, not thousand-line documents.

Here is a way to review them that does not fall apart at scale.

Why the usual PR review breaks on a large spec

Open a 1,500-line spec PR on GitHub and the failure mode is predictable. You scroll. The source diff is a wall of red and green that does not read like prose. The rich diff reads better but you cannot comment on a line and it hides the mechanics of what changed. There is no sense of progress, so after twenty minutes of scrolling you are not sure which sections you actually read and which ones your eyes slid over. You approve. Some sections were read closely. Others were skimmed. Nobody, including you, can tell which is which.

That is not a discipline problem. It is a tooling problem wearing a discipline costume. The tools give you no way to track what has been reviewed, so "review the whole document" quietly degrades into "review the parts I happened to focus on."

A workflow that holds up

The goal is simple to state and hard to do by force of will alone: read every section deliberately, decide about each one, and know when you are actually finished. Structure makes that possible.

1. Read it as a document first, not as a diff

Before you judge any change, understand what the spec is trying to say now. Read the rendered result, the version a future engineer will read, not the raw Markdown. If you start from the diff, you review edits in isolation and never step back to ask whether the whole thing is coherent. AI-generated specs fail most often at the level of coherence: two sections that each read fine but contradict each other, a requirement stated in one place and quietly dropped in another.

2. Then review section by section, and track it

Break the document at its headings and treat each section as a unit you explicitly finish. For each section, ask the same three questions:

Is it true? Does this match reality, the codebase, and the other sections? AI is confidently wrong in ways that read smoothly.
Is it complete? What did it skip? Missing edge cases and unstated assumptions are the expensive failures, and they are invisible in a diff because absence does not show up as a red line.
Is it specific enough to build from? Vague-but-plausible is the default failure mode of generated specs. "The system handles errors gracefully" is not a requirement. Flag it.

The important word is track. Mark each section reviewed as you finish it, so that "done" means every section was deliberately closed out, not "I ran out of patience." If you cannot see your own progress, you cannot tell thorough review from skimming.

3. Comment where the problem is, not in a summary

A review that ends in one big comment saying "looks good, a few concerns" is not actionable. Anchor each concern to the exact line that provoked it. This forces specificity, it gives the author something precise to fix, and it turns your review into a checklist the PR can be measured against.

4. Re-review only what changed

The author pushes fixes. You do not want to re-read 1,500 lines to check five edits, but you also cannot trust "I only changed section 4" without verifying. Scope the re-review to the new commits. Any section you marked reviewed that got touched again should stop counting as reviewed until you look at it again, because an edit can invalidate the reading you already did.

Where tooling has to carry the load

Steps like "track every section" and "invalidate a section when it changes" are not things a human reliably does by willpower on a thousand-line document. They are things a tool should do for you. This is the gap Markdown Review is built for, and it is why the workflow above maps directly onto how it works:

Read the document, not the raw file. The rendered result and the source diff sit side by side, so you never trade one for the other. Source diff vs. rich diff is the longer argument for why that pairing is the fix.
Section by section, with viewed state. A long spec is broken into collapsible sections by heading. You mark each one viewed, the document shows overall progress, and "did we actually read section 9" has an answer.
Viewed marks self-invalidate. When a section's underlying diff changes, its viewed mark clears, so a late edit cannot hide inside a section you already signed off.
Comment on the exact line, in place. Reading the spec as a document does not cost you the ability to comment on the source line.
Scope to a commit range. After the author pushes fixes you can review just the new commits instead of re-reading the whole document.

Everything else stays on GitHub. The PR, the approval, and the merge do not move. What changes is that "reviewed" starts to mean every section was read on purpose, which is the only thing that makes an AI-generated spec safe to build on.

The one-sentence version

AI can generate a 1,500-line specification in minutes. A human still has to review it carefully, and "carefully" means deliberately, section by section, with a way to know when you are actually done. Give the reading the structure the writing skipped, and a generated spec becomes something you can trust instead of something you hope is right.