A4.4 · The spec layer
From stories to a .stories.md
A spec lists what an increment delivers. The stories file answers a different question — who wants each deliverable, and how we will know it works.
The contract between the two files is one rule: every deliverable is realized by at
least one story, and every story names the invariants it encodes. A .stories.md
ends with a Coverage line that maps each deliverable to the stories that realize it —
and a deliverable absent from that line has no covering story. Pick a deliverable on the right to build the
map; three dives walk the move end to end.
Build the coverage map · pick a deliverable
The contract between a spec and its stories
A spec answers what we build and how we know it is right. Its Deliverables section lists the
concrete artifacts the rung produces. The .stories.md answers a neighbouring
question — who wants each deliverable, and how we will know it works — as Connextra user
stories (as a … I want … so that …) with Given/When/Then acceptance and an
INVEST line. Two files, two questions, one rung.
The rule that binds them is plain: every deliverable is realized by at least one story, and every story names the invariants it encodes. A stories file records this with a single Coverage line at its end — a map from each deliverable to the stories that realize it. A deliverable that does not appear in the Coverage line has no covering story, and the rung cannot yet be accepted as done. The hero figure builds that map over the real F6.1 file; the dives read it line by line.
A list of deliverables is turned into a map of stories that realize them: every deliverable is covered, and every story names the invariants it exercises.
F6.1's seven deliverables map to five stories, recorded in the Coverage line. Each story's INVEST line names the F6.1 invariants it encodes — for example US2 encodes the master invariant.
A spec lists deliverables; the stories file covers them — and the Coverage line is the record that no deliverable is left without a story.
The three dives
Each dive takes one move, in the arc build → record → read: build the deliverable→story map, read the Coverage line that records it, then read what each story carries on its INVEST line. Read them in order — A4.4.1 starts.
Deliverable to story
Every deliverable is realized by at least one story. Build the F6.1 map over D1…D7 and US1…US5, and watch an uncovered deliverable surface as a gap.
The Coverage line
The single line that records the deliverable→story map, read verbatim from the F6.1 file — and how a missing deliverable shows up the moment it is read.
INVEST and invariants
Each story's INVEST line names the invariants it encodes and whether it is testable. Read US2's line back to the F6.1 invariant it exercises.
After A4.4, the next module — A4.5 · Invariants — separates a property that must always hold from an acceptance check that holds for one scenario. Return to the A4 chapter navigation to continue.
References
The user-story and coverage tradition this module draws on, and where it connects in the course.
Sources
- Cohn, M. — User Stories Applied — Connextra stories and acceptance, the derived face of a requirement.
- Wake, B. — INVEST in Good Stories — the six properties named on every story's INVEST line.
- Adzic, G. — Specification by Example — deliverables made concrete and checkable through examples.
Related in this course
- A4.4.1 · Deliverable to story
- A4.4.2 · The Coverage line
- A4.4.3 · INVEST and invariants
- A2.03 · INVEST — the properties of a good story.
- A2.04 · Acceptance criteria — Given/When/Then, the story's proof.
- A4 · The spec layer — the chapter.
- F6 · The Portal on the web (Phoenix) — the real chapter these stories accept.