Four iteration loops, and the one that worked
How To Iterate a Specification Driven Design
In Specification Driven Design the specification is the source of truth and code is generated from it. The hard part is not the first build — it is the second. When a defect or a change request arrives, how do you fold it back without letting the specification rot, without rebuilding the whole system, and without losing the change in a backlog? This paper traces four approaches to that question, the way each one failed, and the model that replaced them: edit the specification directly, contain the blast radius with typed encapsulation, and let an interface‑based dependency tree decide what to rebuild.
Core Ideas
💡
The specification is the source of truth — so iterate the specification, not the code Every loop that tried to capture changes somewhere other than the specification eventually let the specification rot. The durable answer is to edit the specification directly and re-apply it.
💡
Fragility is architectural, not a tracking problem A one-line storage change rippling through the whole system is a symptom of code reaching past its boundaries. Typed encapsulation classes absorb the change so most of the system never needs to know.
💡
The dependency boundary is the interface, not the file A specification edit dirties a downstream artifact only when the typed interface or the API contract it depends on actually changes. A storage-internal change dirties nothing.
💡
Staleness must survive a clone Modification times do not survive git. Recording a content hash per input file at build time is the durable signal — and a Version bump changes the hash for free.
💡
One action, three intentions SPEC edits the specification, TGT patches code in an emergency, BOTH does both in one session. BOTH is the default because it never lets the two drift apart.