← Back to slide 06Repository →

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.

1 Specified2 Agreed3 Met

The order of a change

  1. A change request arrives. Six months after the first release: "Add a gift message."
  2. 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.
  3. 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.
  4. 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.

motion study v0.8.0

The gift message, worked through

DocumentWhat changedVersion
FSDFS-013 · gift message, 200 charactersv1.0.0 → v1.1.0
TSDTS-007 · the message is stored with the orderv1.0.0 → v1.1.0
ScreenflowConfirmation must show the message toov1.0.0 → v1.1.0
Storyboardthe gift field drawn on the checkoutv1.0.0 → v1.1.0
ADR-007unchanged: the decision still holdsaccepted

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.

  1. Change requestAdd a gift message
  2. FSDv1.0.0v1.1.0 · FS-013✓ approvednot approved✓ approved
  3. TSDv1.0.0v1.1.0 · TS-007✓ approvednot approved✓ approved
  4. Screenflowv1.0.0v1.1.0✓ approvednot approved✓ approved
  5. 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

Garden 2
  1. ✓Basket
  2. 2Checkout
  3. 3Confirmation
A fiddle-leaf fig with large glossy green leaves, in a terracotta pot

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

© GardenDelivery · Returns · Privacy
Build 1 from slide 05cites FS-010…012 · screen-checkout-1 · ✓ checks pass
Build 2cites FS-013 · TS-007 · screen-confirm-1 · ✓ checks pass
FSDv1.0.0TSDv1.0.0flowv1.0.0boardv1.0.0

_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.