The example is the spec

Specification by example replaces a prose requirement — “enrolment is idempotent” — with a concrete, behavioural illustration: “Given an already-enrolled learner, When they enrol again, Then no duplicate is created.” The example is not a note about the spec; written as a scenario, it is the spec. There is nothing more precise behind it to consult, because the concrete behaviour is the whole of what was agreed.

What makes the example powerful is that it is shared. The same scenario is read three ways, with no translation step between them. Product reads it as the agreed behaviour — the promise. The Operator reads it as the acceptance check — the test of done. The Author — the Claude agent — reads it as the precise behaviour to implement against. The Confirmation was already this shape; A2.02.2 called it “a Given/When/Then skeleton.” Writing it as a scenario gives it the form everyone reads and a runner can execute.

An example works because it is concrete. “Enrolled exactly once; a second enrol does not change the count” has one reading. “Enrolment works correctly” has many: two readers can both accept it and still mean different things, which is the argument the criterion was meant to end. A criterion with several defensible readings is a criterion nobody can accept against, because acceptance turns on whose reading wins.

Switch the view to compare a Confirmation in abstract prose with the same Confirmation as a concrete scenario. The abstract form is shown in burgundy. The readout reports how many defensible readings each form admits — many for the abstract claim, one for the concrete example — and whether it can be accepted against, computed from the model.

Take the Portal rung “enrol in a course”. Its Confirmation, promoted to the shared definition of done, is one scenario. Product agrees this is the behaviour; the Operator accepts the rung against it; the Author builds Portal.ID.generate(:enrolment) and the enrol path to satisfy it. The same words serve all three — there is no separate “spec document” for the rung, because the example is the spec.

# The Confirmation (A2.02) — now the shared definition of done for the rung.
Scenario: enrolling twice does not duplicate the enrolment
  Given a learner already enrolled in "Functional Programming"
  When  the learner enrols in "Functional Programming" again
  Then  the learner appears in their enrolments exactly once

# product reads it as the promise · the Operator accepts against it · the Author builds to it.
id = Portal.ID.generate(:enrolment)   # the Author's build target — one enrolment id

A concrete example is not documentation about the spec; it is the spec. Written as a scenario, the Confirmation becomes one shared artifact — product’s promise, the Operator’s acceptance check, and the Author’s build target — with a single reading and no translation between the three. Abstract prose admits many readings and cannot be accepted against. With the example fixed as the spec, the closing dive turns it into the acceptance test itself.

Primary sources for examples as the shared specification, and where it connects in the course.