A4.6 · Traceability · dive 1
The chain
Every artifact carries a stable id, and every id is reachable from intent to proof. The chain is the spine of “correct by definition.”
A deliverable is realized by a story; the story is accepted by a Given/When/Then and encodes an invariant; the deliverable is also built by an agent story governed by a requirement, proven in turn. Step each link on the right over the Portal's real F6.1 ids — the path is read from the text, never inferred.
Step each link · F6.1 intent to proof
The chain, link by link
Traceability means each artifact carries a stable id so the path from intent to proof is explicit. The chain runs straight down: a deliverable is realized by a user story; the story is accepted by its Given/When/Then and encodes an invariant; the deliverable is also built by an agent story, which is governed by a requirement, proven by an invariant or an acceptance test.
None of these links is inferred. Each is named in the text: the stories file's Coverage line records which
stories realize each deliverable, each story's INVEST line names the invariant it encodes, and each
requirement carries its [US: …] tag. That is what lets a reader — or a
Claude Author — walk the rung end to end and confirm nothing is left unpinned.
# specs.approach.md — the traceability chain (verbatim). Deliverable (fN.M.md · FN.M-D#) └─ realized by → User story (fN.M.stories.md · FN.M-US#) ├─ accepted by → Acceptance criteria (Given/When/Then on the story) └─ encodes → Invariant (fN.M.md · FN.M-INV#) └─ built by → Agent story (fN.M.llms.md · FN.M-AS#) └─ governed by → Requirement (fN.M.llms.md · FN.M-R#) └─ proven by → Invariant (FN.M-INV#) or an acceptance test
- deliverable
- A concrete artifact named in the spec (
f6.1.md) with an idFN.M-D#— e.g. F6.1-D4, the course controller. - realized by
- The user story that delivers the value — recorded in the stories file's Coverage line, so every deliverable maps to at least one.
- encodes
- The invariant a story exercises, named on its INVEST line (
encodes FN.M-INV#) — the path that makes every invariant reachable. - governed by
- The requirement an agent story is built under, tagged
[US: FN.M-US#]and proven by an invariant or an acceptance test.
Resolve an id from the text
Because every link is named, an id resolves without judgement. Pick a deliverable and the Coverage line gives the stories that realize it; pick a story and its INVEST line gives the invariant it encodes. The block below holds the three real F6.1 lines verbatim. Select an id and the readout names its kind, where it lives, and what it links to — read straight from the file.
Pick an F6.1 id · resolve its links
# f6.1.md / f6.1.stories.md — the three lines this id resolution reads (verbatim). # Deliverable F6.1-D4 — PortalWeb.CourseController.index/2: calls only Portal.courses_of/1 # Coverage D4→US2,US3,US5 # Story F6.1-US2 — "As a visitor, I want to open a course page…" encodes F6.1-INV1 # Invariant F6.1-INV1 (master) — PortalWeb calls only the Portal facade
An id resolves from the file, not from opinion: the Coverage line and the INVEST line name every link, so the chain is walkable by reading.
The chain on the Portal
On the Portal — the learning platform this course builds — the worked rung is F6.1, the web
chapter's bootstrap, drawn from F6.1 · Bootstrap the Phoenix PortalThe first web rung: stand the F5 engine up as a Phoenix app, with one facade-backed route and a liveness route.View the spec ladder →.
Take F6.1-D4, the course controller. Its story is F6.1-US2, the F6.1 draft “see a user's
courses”; its draft acceptance is the Given/When/Then “given a known user id, when the page
renders, then it shows that user's courses”; the invariant it encodes is F6.1-INV1, the master rule
that the web layer calls only the Portal facade. The deliverable is also built by an
agent story governed by a requirement tagged [US: F6.1-US2], proven by F6.1-INV1 or
its acceptance test.
That F6.1 draft named a /courses/:user_id page; F6.5 · Views with HEExThe HEEx rung that server-renders the catalog and reconciles the learner route into the protected /my/courses.View the spec ladder →
reconciled the surface to the protected /my/courses — a learner's own
enrollments, no :user_id in the URL. The facade function it calls,
Portal.courses_of/1, is unchanged across both rungs.
One deliverable, walked from intent to proof, every link named in the F6.1 triad. The framework that implements this rung is taught in F6 — the Portal on the web; here the concern is only the chain of ids, not the code.
# Walk F6.1-D4 from intent to proof — every link read from the triad. F6.1-D4 # deliverable: PortalWeb.CourseController.index/2 (f6.1.md) → realized by F6.1-US2 # "see a user's courses" (Coverage: D4→US2,US3,US5) → accepted by Given/When/Then # known user id → renders that user's courses → encodes F6.1-INV1 # master: web calls only the Portal facade (INVEST line) → built by agent story # F6.1-AS# [implements F6.1-US2] (f6.1.llms.md) → governed by F6.1-R# # requirement [US: F6.1-US2] → proven by F6.1-INV1 / acceptance test
Every artifact carries a stable id, so the path from intent to proof is explicit and walkable from the text — not inferred and not asserted.
F6.1's ids form one walkable chain over the real triad: D4 → US2 → its Given/When/Then → INV1, and the agent story → requirement → proof.
A chain of stable ids makes a rung readable end to end: pick any deliverable and walk it forward to the check and the invariant that prove it, without guessing.
Recap — intent to proof, by id
The chain links every artifact id from intent to proof: deliverable realized by a story, story accepted by a
check and encoding an invariant, deliverable built by an agent story governed by a requirement proven in
turn. Each link is named in the text — the Coverage line, the INVEST line, the [US:
…] tag — so the rung is walkable by reading. With the chain in hand, the next dive draws
the rule that makes it a guarantee.
Next in A4.6: A4.6.2 · The closure — the completion rule, clause by clause, and what “run, not asserted” means.
References
The sources behind the traceable chain, and where it connects in the course.
Sources
- Adzic, G. — Specification by Example — examples that double as the executable acceptance the chain ends in.
- Cohn, M. — User Stories Applied — the story as the unit a deliverable is realized by.
- Humble & Farley — Continuous Delivery — traceable, runnable checks as the basis for done.
Related in this course
- A4.6 · Traceability — the module hub.
- A4.6.2 · The closure — the next dive.
- A2.04 · Acceptance criteria — the Given/When/Then the chain is accepted by.
- A1.05 · Correct by definition — the idea the chain serves.
- F6 · The Portal on the web (Phoenix) — the real chapter F6.1's ids come from.