jonnifyagile agents
jonnify / Agile Agent Workflow / A4 · Spec / A4.3 · Anatomy of a spec

A4.3 · The spec layer

Anatomy of a spec

A spec is six named sections. Read them in order on a real one and the shape becomes a template you can write any rung to.

Goal, Rationale, Scope, Deliverables, Invariants, Definition of Done — each answers a different question. Together they constrain the build without over-specifying the solution: they say what must be true, never how to write the code. Pick a section on the right to read it on the Portal's real f6.1.md. Three dives: the six sections, the five Ws, and the line between constraining and over-specifying.

The six sections Constrain, not over-specify The three dives References

Pick a section · read it on f6.1.md

1 · Goal 2 · Rationale (5W) 3 · Scope (In / Out) 4 · Deliverables 5 · Invariants 6 · Definition of Done
Goal · question: where does this rung land? · verbatim: "After F6.1, the Portal runs as a Phoenix app".

Six sections, in order

A spec is a structured document, not free prose. The Portal's real rung spec carries six named sections, each answering a different question, each in a fixed order. Goal sets the destination; Rationale gives the five Ws; Scope draws the boundary with an In and an Out; Deliverables list the concrete artifacts; Invariants name what must always hold; and the Definition of Done closes it as a checklist.

The hero figure walks the six in order. Read them and a spec stops being a blank page: it is a template, and writing one for a rung of your own is filling in six known questions. Each section is unpacked in the dives, with every phrase verbatim from .

Goal
The destination in prose, verbatim: “After F6.1, the Portal runs as a Phoenix app…”.
Rationale
The five Ws — why, what, who, when, where — the reason for the rung before its definition.
Scope
The boundary: In is what this rung builds; Out defers, naming the rung each concern moves to.
Deliverables
The concrete artifacts, F6.1-D1…D7 — e.g. D6 the /health liveness route.
Invariants
Properties true for every value, always — F6.1-INV1, the master invariant, names them.
Definition of Done
A checkbox list, closing on the traceability sentence that every deliverable maps to a story.

Over the whole spec sits the master invariant, verbatim: “The web layer calls only the Portal facade and renders only the closed %Portal.Error{} set.” It is named in the Invariants section as F6.1-INV1.

Constrain the build, not the solution

The job of every section is to constrain the build without over-specifying the solution. A constraint states what must be true and leaves the code free; an over-specification dictates the code and leaves the Author nothing to decide. The cleanest place to see the line is Scope's Out: it constrains by deferring — naming the later rung each concern moves to — not by forbidding it forever.

The figure classifies statements. “renders the empty state for an unknown id” constrains: it fixes a behaviour and leaves the implementation open. “use a case not a cond” over-specifies: it dictates a solution detail the spec has no business holding. The two figures teach different moves — the hero reads the six sections, this one tests one statement against the line.

Constrains or over-specifies? · pick a statement

"renders the empty state for an unknown id" a statement that could appear in a spec CONSTRAINS states what must be true leaves the code free OVER-SPECIFIES dictates the solution leaves nothing to decide
"renders the empty state for an unknown id" · constrains — it fixes a behaviour and leaves the implementation open. A spec states what must be true.

A spec constrains the build without over-specifying the solution — and Scope's Out constrains by deferring, naming the later rung.

The three dives

Each dive takes one part of the anatomy, in the arc read → reason → draw the line: the six sections read in order, the Rationale's five Ws, and the rule that a spec constrains the build without over-specifying the solution. Read them in order — A4.3.1 starts.

A4.3.1built

The six sections

Goal, Rationale, Scope, Deliverables, Invariants, Definition of Done — the fixed order read section by section on the real f6.1.md.
A4.3.2built

The five Ws

The Rationale answers why, what, who, when, and where — the reason for a rung, fixed before its definition so the Author never invents it.
A4.3.3built

Constrain, not over-specify

The line every section holds: state what must be true, never how to write the code. Scope's Out constrains by deferring.

After A4.3, the chapter turns from reading a spec to deriving its proof: the next module — A4.4 · From stories to a .stories.md — builds the stories file every deliverable is realized by. Return to the A4 module navigation to continue.

References

The specification tradition this anatomy draws on, and where it connects in the course.

Sources

Related in this course