SAMPLE SESSION · MODULES 01–03
From an ambiguous request to a specification an agent can build from
A representative lecture from the first half of the course. It takes a one-line feature request, shows what a coding agent actually does with it, and rebuilds it as a specification with acceptance criteria and traceable evidence.
14 slidesAbout 45 minutes of teaching plus a 30-minute exerciseInstructor notes included
Illustrative teaching material for Spec-Driven Development. Condensed for the web; the live session includes the walkthrough, the handout and the exercise review.
SPEC-DRIVEN DEVELOPMENT · SESSION 03
Make intent precise.
Make delivery verifiable.
What a specification has to settle before anyone — human or agent — writes a line of code.
THE PREMISE
A model can write the implementation.
It cannot decide what correct means.
Correctness is a claim about your users, your obligations and your existing system. None of that is in the weights. It arrives only if someone puts it there.
WHERE THE HOUR GOES
The work did not disappear. It moved.
Before assisted development
- 10 min — understand the request
- 10 min — decide the approach
- 35 min — write the implementation
- 05 min — write the tests
After, done badly
- 02 min — paste the request
- 03 min — accept the output
- 40 min — review, rework, re-review
- 15 min — defect found in staging
After, done well
- 25 min — specify behaviour and evidence
- 05 min — bound the agent task
- 10 min — implement and iterate
- 05 min — verify against the spec
The third column is not slower than the second. It is the same hour, spent where it compounds instead of where it repeats.
THE PROBLEM, DRAWN
One sentence, four defensible readings
THE MISSING DECISIONS
Four questions a prompt almost never answers
- 01What must never happen?
Non-goals and forbidden states. Most agent over-reach is enthusiasm, not incompetence — it built the thing you did not ask it to stop building.
- 02What happens when it fails?
Timeouts, partial writes, a payment that succeeded while the confirmation did not. Failure behaviour is behaviour.
- 03Who is allowed to do this?
Authorisation is a requirement, not an implementation detail, and it is the one most often inferred wrongly.
- 04How will we know it worked?
If no one can name the evidence, the requirement is a preference with good posture.
THE ARTEFACT
What a working specification contains
WORKED EXAMPLE
The same feature, specified
# Slice: paid registration for a published cohort
## Problem
A learner can currently pay twice for the same cohort. Finance reconciles
the duplicates by hand, roughly four times a month.
## Non-goals
- Refunds and partial refunds (handled by finance, out of scope).
- Waiting lists for full cohorts (separate slice, not this one).
- Any change to pricing or currency conversion.
## Behaviour
B1 A learner may hold at most one paid registration per cohort.
B2 A second completed payment for a cohort the learner already holds
MUST NOT create a second registration, and MUST be recorded for
finance review with the original registration referenced.
B3 Registration is refused at or after the published deadline instant.
The instant is inclusive of the final second and evaluated in UTC.
B4 A payment that fails, expires, or is disputed leaves no confirmed
registration behind and sends no welcome message.
## Contracts
registration := { id, application_id, cohort_id, learner_email,
paid_at (UTC), payment_ref (unique) }
UNIQUE (cohort_id, learner_email) WHERE status = 'paid'
## Acceptance criteria
AC1 (B1) Two completed payments, same learner and cohort → exactly one
row in registrations; second attempt recorded as duplicate.
AC2 (B3) A payment completed at deadline − 1s registers; at deadline
+ 0s is refused with a deadline-passed reason.
AC3 (B4) A failed payment webhook produces zero registrations and zero
sent messages, asserted against the outbox.Every line above is a decision someone had to make. The agent makes all of them either way — the only question is whether a human saw them first.
CRAFT
An acceptance criterion you cannot argue with
Not yet a criterion
- “Registration should be reliable.”
- “Handle duplicate payments gracefully.”
- “The deadline should be respected.”
- “Send the learner a confirmation.”
A criterion
- “Two completed payments for the same learner and cohort produce exactly one registration row.”
- “The second payment is recorded with a reference to the first and does not send a second message.”
- “A payment completing at deadline + 0s is refused with reason deadline_passed.”
- “Exactly one message is queued per created registration, asserted against the outbox.”
The test: could two reasonable people disagree about whether it passed? If yes, it is still a preference.
THE METHOD
The loop you will run for the rest of the course
CONTEXT
This is not a replacement for the methods you already use
EVIDENCE
Every requirement names the evidence that settles it
BEFORE YOU DELEGATE
The pre-delegation checklist
Run this before any task pack goes to an agent. It takes four minutes and removes most of the rework.
- ✓The slice is small enough that a wrong answer is cheap to discard.
- ✓Non-goals are written down, not assumed.
- ✓Every acceptance criterion is binary and observable.
- ✓Failure behaviour is specified, not left to the implementation.
- ✓Data contracts and validation rules are stated.
- ✓Permitted actions are explicit — what may be created, changed, deleted.
- ✓The definition of done names the evidence, not the effort.
- ✓A review checkpoint exists before anything irreversible happens.
THE HONEST CAVEAT
Specifying is a cost.
Spend it where correctness is contested.
A throwaway prototype does not need a specification. A payment path does. Judgment about which is which is part of the skill, and this course grades it.
YOUR TURN
The exercise
Take the ambiguous request in your handout. Produce a one-page specification with non-goals, four behaviours, one data contract, and an acceptance criterion for each. Then hand it to an agent and see what you forgot.
- 30 minutes to write
- 10 minutes with the agent
- 10 minutes reviewing a neighbour’s spec against their result
Use the arrow keys to move through the deck. Press N for instructor notes, A to read every slide on one page.
THIS IS ONE SESSION OF 7
The full course goes
considerably deeper.
7 modules, three applied assignments, a capstone and a final exam. Starts 28 September 2026.