Read more · slide 06 / 07 · kept true
Change the spec first.
Most of a system's life comes after the first build. The documents stay the source of truth only if every change goes through them first.
The order of a change
- A change request arrives. Six months after the first release: "Add a gift message."
- The documents change first. Each affected document gets a new version. A copy of what was there is kept in the archive before the edit.
- The new versions are agreed again. The same readers, the same pages, the same approval as the first time. A changed page does not keep its old approval.
- Then the agent rebuilds from them. The build cites the new ids, and the checks prove it.
The whole loop, in motion
Build it, keep it, change it, from the same source: the Garden checkout from its first draft to the gift message, in about 25 seconds. Pause or replay it at any time.
The gift message, worked through
| Document | What changed | Version |
|---|---|---|
| FSD | FS-013 · gift message, 200 characters | v1.0.0 → v1.1.0 |
| TSD | TS-007 · the message is stored with the order | v1.0.0 → v1.1.0 |
| Screenflow | Confirmation must show the message too | v1.0.0 → v1.1.0 |
| Storyboard | the gift field drawn on the checkout | v1.0.0 → v1.1.0 |
| ADR-007 | unchanged: the decision still holds | accepted |
Build 2 cites FS-013, TS-007, screen-checkout-1 and screen-confirm-1. The screenflow caught the second page. A code-first change would most likely have missed it.
·Today: every document is at v1.0.0, and approved. 1The request arrives. Nothing is coded yet. 2First, the documents as they stand are kept. 3Then each document changes. It moves to v1.1.0, and it is no longer approved. 4The change is drawn on the storyboard, where you can see it. 5You review the new version, and approve it. 6Now the whole set is at v1.1.0, and approved again. ✓Only then does the agent rebuild, from the new documents. The code changes last.
- Change requestAdd a gift message
- FSDv1.0.0v1.1.0 · FS-013✓ approvednot approved✓ approved
- TSDv1.0.0v1.1.0 · TS-007✓ approvednot approved✓ approved
- Screenflowv1.0.0v1.1.0✓ approvednot approved✓ approved
- Storyboardv1.0.0v1.1.0✓ approvednot approved✓ approved
1CHECKOUTStoryboard v1.0.0 · screen-checkout-1Storyboard v1.1.0 · screen-checkout-1 · FS-013✓ ApprovedNot approved · changed✓ Approved again · by you
- ✓Basket
- 2Checkout
- 3Confirmation

Your order is nearly there.
One plant, one pot, delivery on Thursday.
Fiddle-leaf fig60 cm£38
- Terracotta pot24 cm£14
- DeliveryThursday£6
Total£58
Secure paymentFree returns
_archive · what was there, kept before the edit
Why not just change the code
If the code changes first, the documents start to lie. The next session, the next agent or the next maintainer builds from a description of something that no longer exists. A small shortcut today becomes a guess tomorrow.
Updated first, the documents stay true. A change runs the same loop as the first build, only smaller.
Carries forward: Build 1 from slide 05, ADR-007 from slide 03. The archive is the first of the two promises. See the whole loop in motion: the source-of-truth loop.