A4.1 · The spec layer
Specification by example
An abstract requirement admits many readings; a worked example pins one. The first move of the spec layer is to make the examples the specification.
“Handle bad input” could mean a redirect, a crash, a 404, or an empty page — the phrase does not decide. Replace it with worked examples and the readings collapse to one, before a line of code is written. On the right, contrast the abstract requirement with the examples that pin it. Three dives: examples as the specification, living documentation that cannot drift, and removing ambiguity.
Many readings, or one · switch the view
Examples are the specification
An abstract requirement is a sentence the reader has to interpret. “The page must handle a bad user id” is fine until two people read it: one builds a 404, one builds an empty page, one lets it crash. Each is a defensible reading of the same words, and none of them is what the requirement meant — because the requirement never decided.
Specification by example replaces the sentence with worked cases. Each case is concrete, stated as Given/When/Then, and pins exactly one behaviour. Together the cases narrow the readings to one, and because they are concrete, the build can be held to them: a worked example doubles as the executable check. The ambiguity is removed before a line of code is written, and the documentation cannot later drift from the system — the example is both at once.
Replace the abstract requirement with worked examples. The examples are the specification — concrete, unambiguous, and they double as the executable check.
The Portal's learner-enrollments 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 →, defines the protected /my/courses route by three worked
Portal.Enrollment examples — an enrolled learner, a learner with no
enrollments, and an unauthenticated request — and the acceptance harness reads its checks from them.
A worked example pins one reading and proves it — the specification and the check are the same artifact.
The three dives
Each dive takes one consequence of making examples the specification, in the arc be the spec → cannot drift → remove ambiguity: the example as the specification the harness reads, the living documentation that follows, and the mechanism underneath — readings collapsed from many to one. Read them in order — A4.1.1 starts.
Examples as specification
The concrete examples are not an illustration of the spec — they are the spec, and the acceptance harness reads its checks straight from them. Pinned on the catalog and /my/courses cases.
Living documentation
Because the examples are the checks the build runs against, the documentation cannot drift from the system: a behaviour change that breaks an example breaks a check.
Removing ambiguity
The mechanism the first two relied on: add worked examples until exactly one reading of the requirement survives — before any code is written.
After A4.1, the next module — A4.2 · The triad: spec, stories, agent brief — names which artifact answers which question, so no document is crammed. Return to the A4 chapter navigation to continue.
References
The sources behind examples-as-specification, and where the layer it opens connects in the course.
Sources
- Adzic, G. — Specification by Example — concrete examples as the executable specification; documentation that cannot drift.
- Cohn, M. — User Stories Applied — the conversation a story records and the acceptance that closes it.
- Gherkin reference — Given/When/Then as the structured form a worked example takes.
Related in this course
- A4.1.1 · Examples as specification — the example as the spec the harness reads.
- A4.1.2 · Living documentation — the documentation that cannot drift.
- A4.1.3 · Removing ambiguity — readings collapsed from many to one.
- A4 · The spec layer — the chapter this module opens.
- A4 · The spec ladder — view the F6.1–F6.6 spec content across the iterations git recorded.
- A2.04 · Acceptance with Given/When/Then — the form a worked example is written in.
- A0.2.2 · The four artifacts — the spec a rung's examples define.
- Companion · Phoenix (F6) — the real chapter whose F6.1 examples ground this module.