Critique before you build: what a second reviewer found in our own specs

Our build loop has a rule I did not always follow in the early months. One model plans. A different model critiques the plan. A third builds. Then the reviewer reads the branch. Builder and reviewer are never the same.

This post is about what the critique step found on 4 November, before a line was written.

The setup

On 4 November there were three specs ready for building: SEO (doc 122), the client section and knowledge (123), and articles, market cards and the calendar (124). A separate reviewer, Claude Opus, read all three, read the code read-only, and wrote doc 125. Then a fourth spec arrived, on human-first content, employees and the inbox (127), and doc 128 critiqued that.

Each finding names a file or table that proves it.

What it found in 122 to 124

Five problems cut across all three specs:

1. Two research packs, two citation checkers, two fact shapes. The same machine was specified twice.
2. Three homes for "things the client has done or proved". Three tables for one idea breaks our "one home per thing" rule on day one.
3. Three homes for the offer and two lifetime-value calculators.
4. Migration numbers would collide. Two unmerged branches used the same number, and 0267 to 0269 were missing. The migration runner dedupes by file hash, so duplicates would not fail loudly. The filename sort would decide order, and one spec had foreign keys into another's tables.
5. The time was not there. The specs stated about 2 + 2.25 + 2 days. One spec's own steps added to 23.5 hours. The realistic total was about nine Sonnet days. After cuts, about six, which still did not fit one week.

Specific must-fixes in the SEO spec: Search Console and rank tracking already existed, a new table contradicted its own text, and AI wording cost was unbounded (about Rs 2,500 per site on a 500-page audit).

What it found in 127

The verdict: the research is good and the direction right, but the spec was written partly against the code as it stood before 4 November. Six build steps rebuilt things that already existed: ticket auto-start and its single gate, "Mark as posted", the notification helper, the Manager tab, and the human path in the article workbench. Two would have broken recent decisions. Moving article stages into the engine contradicts ADR-445. Putting cost in micro-dollars breaks the hard rule that AI cost columns are paise.

Two privacy holes in today's code were not mentioned at all. One: the attendance functions took any user id and checked only the role, so any operations user could clock a colleague in or out, or read their times. The register becomes a legal record once IIPTA staff use it. It was fixed in the very next commit (ADR-479): a person acts only on themselves; HR and the super admin can correct someone else with a written reason, and every such correction is logged.

What we did with it

• We reserved ranges before building: each track got its own block of migration numbers and ADR numbers (for example 123 took migrations 0271 to 0274 and ADRs 430 to 439; 124 took 0275 to 0278 and 440 to 449; 122 took 0279 to 0281 and 450 to 459).
• A coordination note listed who owns which files, which shared files take one appended line, and which shared contracts every track uses (purposes, lifetime-value maths, facts and citations, edit-in-place field).
• One short prep commit ran before the four Wave-1 tracks branched, so they shared no file.
• The research pack was built once.

Why I trust the loop

Our own learning log says it plainly: independent review catches real defects. The Session 7 review fixed four; the Session 8 review fixed six. Builder is not reviewer.

What went wrong

Not everything is fixed by review. Even after the cuts the nine-day estimate did not fit a week, so we sequenced work in waves. And the critique itself has limits: it was read-only against a snapshot of the code, and four non-Lab test files still fail on main.

What's still open

Whether the real build time matched the reviewer's nine days is not recorded in what I have. The Wave-1 tracks merged, but I have not measured their cost against the estimate.

Numbers at a glance