A4.7 · Workshop · dive 2
Run the sequence
The spec layer is six moves; the workshop runs them in order on one chapter. Each move produces a named part of the spec, and the parts accumulate until the rung is provable.
By-example, the triad, the anatomy, the stories, the invariants, the traceability chain
— stepped over the F5.1 triad, the spec takes shape part by part. The output is the real
f5.1.md and f5.1.stories.md, reproduced not invented.
Step the pipeline on the right.
Step the six moves · the spec fills
POST /enroll returns 422, an
unknown path returns 404). Each case doubles as the executable check. · 1 of 6 parts
of the spec in place.Six moves, accumulating
The spec layer is not one document written at once — it is six moves, each producing a named part, run in order until the rung is fully defined and provable. The workshop runs them over the F5.1 triad, and the parts accumulate: the abstract requirement collapses into worked examples, the triad splits the work across three files, the anatomy fills section by section, the stories derive from the deliverables, the invariants are stated, and the chain closes.
- by-example
- Replace “handle requests” with F5.1-US1's three worked cases — boot,
POST /enroll→422, an unknown path →404. Each doubles as the check (A4.1). - the triad
- Split the work across
f5.1.md(what & why & done),f5.1.stories.md(who wants what), andf5.1.llms.md(how to build with proof gates) (A4.2). - the anatomy
- Fill the six sections of
f5.1.md— Goal, Rationale (5W), Scope, Deliverables D1–D7, Invariants, Definition of Done (A4.3). - the stories
- Derive five Connextra stories US1–US5 from the deliverables, each with Given/When/Then acceptance and an INVEST line (A4.4).
- the invariants
- State the five — INV1 (the replaceable seam), INV2 (identity), INV3 (supervision), INV4 (pure id functions), INV5 (functional core) (A4.5).
- traceability
- Close the chain: the Coverage line maps every deliverable to a story, so completion is a closure, not a claim (A4.6).
The moves are ordered because each depends on the one before: there are no stories without deliverables, no traceability without stories. Run them out of order and the spec has gaps.
One deliverable through the chain
Stepping the whole pipeline shows the spec fill; this figure follows a single deliverable through it. Pick
one of F5.1's seven, and watch it connect forward: the story that realizes it (read straight
off the Coverage line), the acceptance that story earns (a Given/When/Then from
f5.1.stories.md), and the invariant it touches where one applies.
The two figures teach different moves — the hero steps the whole sequence once; this traces one item end
to end.
The consequence is the lesson: a deliverable is not “done” because it is listed. It is done when a story realizes it and a check accepts it. A deliverable with no story is a hole in the spec — the gap A4.7.3 hunts for.
Trace one deliverable · pick one
A deliverable is done when a story realizes it and a check accepts it — not because it is listed.
The sequence on the Portal
On the Portal — the learning platform this course builds — the six moves run over
F5.1 — Portal's engine-facade rung (the engine chapter's first rung; the seed of the
F6 master invariant). By-example fixes F5.1-US1's three cases; the triad splits
the work; the anatomy fills f5.1.md; the stories derive US1–US5; the invariants
state INV1–INV5; and traceability closes with the Coverage line. The output is not invented — it
reproduces the real f5.1.md and f5.1.stories.md, the
Coverage line included.
Every Portal reference here stays at the spec level — rungs, deliverables, stories, invariants. The one
id contract the course names freely is Portal.ID.generate/1 /
Portal.ID.decode/1; the engine itself is named only through the master-invariant
seed. The framework that implements these ideas is taught in the companion course.
# The six A4 moves run over the F5.1 triad — each produces a named part. # 1 by-example → US1's three cases (boot · POST /enroll → 422 · unknown → 404) # 2 triad → f5.1.md · f5.1.stories.md · f5.1.llms.md # 3 anatomy → Goal · Rationale (5W) · Scope · Deliverables · Invariants · DoD # 4 stories → US1…US5, each Given/When/Then + an INVEST line # 5 invariants → INV1 (replaceable seam) … INV5 (functional core) # 6 traceability→ the Coverage line maps every deliverable to a story # f5.1.stories.md — the Coverage line, verbatim — the chain closes here: Coverage: D1→US1 · D2→US2 · D3→US1 · D4→US1,US3 · D5→US1,US4 · D6→US3,US5 · D7→US4.
The spec layer is six ordered moves; run them on a chapter and each produces a named part — examples, the triad, the anatomy, the stories, the invariants, the closure — until the rung is provable.
The six moves over the F5.1 triad reproduce f5.1.md and
f5.1.stories.md — Goal through DoD, five stories, five invariants, and the
Coverage line that closes them.
The workshop is the sequence applied once: examples to checks, deliverables to stories, invariants stated, the chain closed.
Recap — the spec, part by part
Six moves run in order over the F5.1 triad build the spec part by part: worked examples that double as
checks, the triad that splits the work, the anatomy that fills the six sections, the stories that derive from
the deliverables, the invariants that name what must always hold, and the traceability chain that closes.
Each deliverable connects forward to a story and a check, so nothing in the spec is merely listed. The output
reproduces the real f5.1.md and f5.1.stories.md —
and the next dive checks that the chain actually closes.
Next in A4.7: A4.7.3 · The closed spec — check the produced Coverage line against the real one; the spec is acceptable only when every deliverable maps to a story and the chain closes.
References
Primary sources for running examples-to-stories end to end, and where this dive connects in the course.
Sources
- Adzic, G. — Specification by Example — the process from worked examples to an executable, living specification.
- Cohn, M. — User Stories Applied — deriving stories and their acceptance from what a slice must deliver.
- Humble & Farley — Continuous Delivery — a thin first slice, releasable, with deferred work named not built.
Related in this course
- A4.7 · Workshop: specifying Portal's engine — the module hub.
- A4 · The spec layer — the chapter whose six moves this dive runs.
- A1.05 · Correct by definition — the closure the chain earns.
- F6 · The Portal on the web (Phoenix) — the chapter whose master invariant F5.1-INV1 seeds.
- Companion · Functional Programming in Elixir — where the engine and its ids are implemented.