The six sections

A spec is not free prose. The Portal's real rung spec f6.1.md carries six named sections, each a heading, each answering a different question. Read in order, they are the whole anatomy: the Goal states where the rung lands; the Rationale gives the reason in five Ws; the Scope draws an In/Out boundary; the Deliverables list concrete artifacts; the Invariants name what must always hold; and the Definition of Done closes the spec as a checklist.

The hero figure walks the six. Below, each is named with a verbatim phrase from the file — nothing is paraphrased, because a spec's exact words are its contract.

The six sections sit in a fixed order, and the order is not decorative. Each section assumes the one above it: the Rationale explains the Goal; the Scope bounds what the Rationale promised; the Deliverables realize what is in Scope; the Invariants constrain the Deliverables; and the Definition of Done closes over all of them. Read top to bottom, a spec moves from where to why to how far to what to what must hold to how we know.

Step the order below. The figure names each position and the role it plays — the move this dive teaches is the sequence, distinct from the hero, which reads a single section's words. A spec written to this order is filling in six known questions, never a blank page.

On the Portal — the learning platform this course builds — the real artifact is f6.1.md, the spec for the first rung of the web chapter: stand the headless engine up as a Phoenix app. Its six headings are the anatomy, byte for byte. The Goal names the destination; the Rationale gives the five Ws; the Scope's Out defers Ecto and LiveView to later rungs; the Deliverables list seven artifacts including the /health liveness route; the Invariants name the master rule; the Definition of Done closes on traceability.

The fragment below is the six headings in order — the document's skeleton, with each heading's question in a comment. It is markdown, not code: a spec's body is prose and lists, and the dives read those words. The skeleton is the part you reuse to write a spec of your own.

# f6.1.md — the six sections, in order (headings verbatim; questions in comment).

## Goal             — where does this rung land?
"After F6.1, the Portal runs as a Phoenix app."

## Rationale (5W)   — why, what, who, when, where?
"F5 produced a correct engine but no way for a human to reach it over HTTP."

## Scope            — what is in, and what is deferred?
"Out: ... Ecto persistence (→ F6.3) ... LiveView (→ F6.6)."

## Deliverables     — which concrete artifacts ship?
"F6.1-D6 — a liveness route get \"/health\", ... returning 200 (a plain \"ok\")."

## Invariants       — what must always hold?
"PortalWeb calls only the Portal facade and renders only %Portal.Error{}."

## Definition of Done — how do we know it is done?
"Every deliverable maps to a user story and every invariant is exercised by a check."

A spec carries six named sections: Goal, Rationale, Scope, Deliverables, Invariants, and Definition of Done. They sit in a fixed order, each assuming the one above it — where, why, how far, what, what holds, how we know. Read on the Portal's real f6.1.md, the order is a template you fill in to write any rung. With the headings in hand, the next dive reads the section that carries the reason: the Rationale's five Ws.

The specification sources behind the anatomy, and where the six sections connect in the course.