From an ambiguous request to a specification an agent can build from

This is a representative sample session, not the complete course.

Session

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.

Runtime

About 45 minutes of teaching plus a 30-minute exercise

Slides

Eyebrow

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.

Notes

Open by asking the room how many have shipped something an AI assistant wrote this week, and how many could state the acceptance criteria it was written against. The gap between those two numbers is the whole course.

Eyebrow

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.

Notes

Resist the framing that this is about model quality. A perfect model still cannot know that finance requires a duplicate-payment guarantee unless it was told.

Eyebrow

WHERE THE HOUR GOES

The work did not disappear. It moved.

Columns

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

Note

The third column is not slower than the second. It is the same hour, spent where it compounds instead of where it repeats.

Notes

Emphasise: nobody in column two is lazy. They are doing exactly what the tool invites. The method is what changes the invitation.

Eyebrow

THE PROBLEM, DRAWN

One sentence, four defensible readings

Every branch on the left is an implementation a competent engineer could justify from the same request. The agent picks one and states it with total confidence.

Notes

Ask the room which of the four readings is wrong. The point is that none of them are — the request simply never said.

Eyebrow

THE MISSING DECISIONS

Four questions a prompt almost never answers

Bullets

What 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.

What happens when it fails?

Timeouts, partial writes, a payment that succeeded while the confirmation did not. Failure behaviour is behaviour.

Who is allowed to do this?

Authorisation is a requirement, not an implementation detail, and it is the one most often inferred wrongly.

How will we know it worked?

If no one can name the evidence, the requirement is a preference with good posture.

Notes

These four questions are the minimum viable specification. If a team adopts nothing else from this course, this slide still pays for it.

Eyebrow

THE ARTEFACT

What a working specification contains

Six layers. Not six documents — in practice this is one page for a small slice and four for a significant one.

Notes

Stress that length is not the metric. A decisive page beats an exhaustive twelve.

Eyebrow

WORKED EXAMPLE

The same feature, specified

Language

Specification excerpt · course registration

# 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.

Note

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.

Notes

Walk B2 slowly. “MUST NOT create a second registration” and “MUST be recorded for finance” are two requirements hiding in one sentence; show how you would split them in review.

Eyebrow

CRAFT

An acceptance criterion you cannot argue with

Columns

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.”

Note

The test: could two reasonable people disagree about whether it passed? If yes, it is still a preference.

Notes

Have the room rewrite one of their own tickets into this form. It is the single highest-yield five minutes in the session.

Eyebrow

THE METHOD

The loop you will run for the rest of the course

The specification is upstream of the agent and downstream of verification. The feedback arc is what stops it becoming waterfall.

Notes

Name the arc explicitly: change requests are expected, versioned, and cheap. That is the difference from big-design-up-front.

Eyebrow

CONTEXT

This is not a replacement for the methods you already use

Spec-driven development occupies the layer that became load-bearing once implementation stopped being written by hand.

Notes

Pre-empt the “isn’t this just BDD?” question here rather than in the Q&A. Answer: BDD is one good way to express layer four of the specification.

Eyebrow

EVIDENCE

Every requirement names the evidence that settles it

The matrix is boring and it is the artefact that survives review, handover and audit. An empty cell is a finding.

Notes

Point at REQ-04. Ask what a reviewer should do. The answer is block, not “note for later”.

Eyebrow

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.

Items

• 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.

Notes

Give them this as a printed card. Teams that keep it on the wall report the largest drop in review cycles.

Eyebrow

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.

Notes

Say plainly that over-specification is a real failure mode. Credibility with experienced engineers depends on saying this out loud.

Eyebrow

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.

Bullets

• 30 minutes to write
• 10 minutes with the agent
• 10 minutes reviewing a neighbour’s spec against their result

Notes

The neighbour review is the part that teaches. Everyone finds their own spec clear.