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 — expected design.md.review.md; the instance holds findings for: requirements.md)
       [review-gate] review gate: "tasks.md" has no completed review (no findings file — expected tasks.md.review.md; the instance holds findings for: requirements.md)
   
     Next steps:
       1. Review each artifact and record the findings: `aidlc review price-alerts design.md` and `aidlc review price-alerts tasks.md`.
       2. Run `aidlc transition price-alerts` again.

   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, names what's absent, and ends with numbered next steps. 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 waved through as a matter of routine, and a check that's waved through 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.

   So the review runs in a separate agent, aidlc-reviewer, that starts fresh and cannot edit files. On Claude Code that is .claude/agents/aidlc-reviewer.md, and a hook allows it only git diff, git log and the compliance checks. On Codex it is an agent in a read-only sandbox. aidlc init installs it on both. Because it cannot write, it hands its findings back and the session that called it writes the file. On other platforms there is no agent file. The review skill spawns a fresh sub-agent and tells it to edit nothing. That is a request, not a lock, so say so at the top of the review and read it knowing that.

   The same reviewer can check the build. On Claude Code and Codex, the implementation skill offers to hand each task in tasks.md to a fresh agent, so task 8 does not inherit tasks 1 to 7. Then the reviewer checks that task against the criteria it cites. Only after that check passes is the task ticked and committed. It is off unless you ask for it, because it roughly doubles the agents.

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 disagree with a finding

   Sometimes the review gets it wrong. The finding was a misunderstanding, or the risk is real and you accept it.

   Do not look for a way around the gate. Settle the finding, in the file that records it. Open design.md.review.md and change the status line of that finding to one of three words, with a reason after it:

   - **Status:** accepted-risk — a price of 0 never reaches the engine; the feed drops it
   

   resolved means you fixed it. accepted-risk means it is real and you are living with it. rejected means the reviewer was wrong. Only open blocks. The reason sits in the file, in your git history, where the next person can find it.

   There is one flag that sounds like the way out and isn't: aidlc transition --override. It skips the ownership gate, the one that stops you moving work someone else has claimed. It does not touch reviews. Only a person may run it; an agent is refused.

   Settle a finding when you have decided it is wrong or acceptable. 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 settle a finding on the record. You know the review runs in an agent that cannot edit your files, and that each build task can get the same treatment.

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