The deep dive · chapter 3 · 7 steps

The check that says no

What a blocked transition looks like, how to read it, and why the review of your own design is written to be hostile on purpose.

1. 1. The problem — "done" that isn't

   Everyone has shipped something that was done. The tests passed, the pull request merged, and three weeks later it turned out the requirement nobody wrote down was the one that mattered. "Done" had meant I stopped working on it.

   Checklists don't fix this, because a checklist you fill in yourself measures your optimism. What fixes it is a check that refuses to advance, costs you something now, and tells you precisely what's missing.

2. 2. Watch it refuse

   Step through a real block, from the refusal to the fix:

   What "no" looks like

   aidlc — zsh

   $ aidlc transition price-alerts
   
   ✗ Transition blocked for instance "price-alerts"
   
     Violations:
       [review-gate] review gate: "design.md" has no completed review
                     (no findings file)

   why it refused

   The full-feature template asks
   for a hostile review of design
   before implementation starts.
   
   No review file exists yet, so
   the answer is no.

   ← backstep 1 of 4next →

   Notice the shape of the refusal. It doesn't say "requirements not met" — it names the file, names the rule, and names what's absent. That's the whole design goal of a gate: a check that fails should tell you what to do next, not that you have failed.

   Notice also that the second attempt was also refused. Writing the review wasn't enough. A review that found a serious hole and was then ignored is not a review; it's a file.

3. 3. Why the review is hostile

   The review step doesn't ask "does this look reasonable". It works through a fixed list of ways a document can be wrong:

   • Ambiguities — vague words, undefined behaviour.
   • Contradictions — two requirements that can't both hold.
   • Missing edge cases — the input nobody considered.
   • Untestable criteria — a requirement with no observable pass or fail.
   • Hidden assumptions — the precondition nobody wrote down.
   • Security gaps, scalability concerns, scope creep.

   Every finding gets a severity, and only critical findings block. That threshold is deliberate: a check that blocks on everything gets overridden as a matter of routine, and an override that's routine is not a check.

   The aidlc-review skill also says something inconvenient: whoever wrote the document should not be the one reviewing it. Self-review finds the problems you already knew about and misses the ones you can't see, which are the expensive ones. Where a genuinely separate reviewer isn't available, the honest move is to say so at the top of the review and read it knowing that.

4. 4. What a gate actually checks

   Two different things, and they're worth separating.

   Conditions for finishing a step. Do the required documents exist, and are they marked complete? This is mechanical and boring and catches the most common failure, which is moving on with a document half-written.

   Conditions for starting the next one. For example: implementation won't start unless a git branch exists. That sounds fussy until the first time somebody implements a feature straight onto the main branch.

   Both run the same way. In your terminal, aidlc transition evaluates them before moving. In your build pipeline, aidlc gate <name> <step> exits 0 or 1, so the same rules can block a merge:

   aidlc gate price-alerts testing
   

   The strictest of them all guards the testing step, and it is worth knowing about before you meet it: it reads the numbered criteria out of requirements.md and fails if any of them has no test referring to it. Which means the practical consequence of writing a vague requirement isn't a philosophical debate — it's a red build.

5. 5. When you need to go anyway

   Sometimes the check gets it wrong. The requirement it wants was genuinely not applicable; the review finding was a misunderstanding.

   aidlc transition price-alerts --override
   

   Two things about this. It exists, because a check with no escape hatch gets disabled entirely. And it's recorded, so "we overrode the design review" is a fact somebody can find later rather than a thing that quietly happened.

   Use it when you've decided the check is wrong. Not when you'd rather not do the work.

6. 6. Checkpoint

   checkpoint

   The review of your design turned up one serious hole. What happens if you leave it recorded and try to move on?

   • You are blocked until it is dealt with.
   • You get a warning and it moves on.
   • Nothing — writing the review was the requirement.

   This checkpoint needs JavaScript.

7. 7. What you can do now

   You can read a blocked transition and know exactly what to do about it, and you can tell the difference between a check worth satisfying and one worth overriding on the record.

   Next: the notes AIDLC keeps about your codebase, and why they mean your assistant stops reading the same files over and over.