A4.2 · The spec layer
The triad
A rung is not specified by one document. It is specified by three — the spec, the stories, and the agent brief — each answering exactly one question.
The spec answers what we build, why, and when it is done. The
stories answer who wants what, and how we will know. The agent brief
answers how to build it, with proof gates. Cram all three into one file and each reader is failed; keep
them apart and each file reads for one audience. The real triad is F6.1 · Bootstrap the Phoenix PortalThe first web rung: stand the F5 engine up as a Phoenix app, with one facade-backed route and a liveness route.View the spec ladder → — f6.1.{md,stories.md,llms.md};
the second, fittingly, is the course's own a4.*. Three dives: which question, the real
triad, and the course itself.
One question per file
A specification of a rung must say three different things, and each thing has a different reader. What we build and why and when it is done is the contract, read by an author and a reviewer. Who wants the rung and how we will know it works is the user's side, read by product and QA. How an agent builds it, with the gates that prove it is the brief, read by a coding agent. Three questions, three readers, three files.
The discipline is keeping them apart. One file per question means each reads cleanly: the contract is not buried in build steps, the stories are not buried in references. Select a question below and the figure names the one file that answers it — over the real F6.1 triad, the spec for the Portal's first web rung.
Pick a question · the file that answers it
One artifact per question, no document crammed: the spec answers what & why & done, the stories answer who wants what, the brief answers how to build with proof gates.
The rung F6.1 is specified by f6.1.md / f6.1.stories.md /
f6.1.llms.md — and this course's own a4.* is the
same triad, one level up.
Three questions, three files — and a rung is specified only when all three are answered apart, not crammed into one.
The three dives
Each dive takes one part of the triad, in the arc name the question → read the real files → see
the course do it to itself: which question each file answers, the real f6.1.*
triad read row by row, and the course's own a4.* triad as the same shape. Read them
in order — A4.2.1 starts.
Which question?
The three questions a rung's specification answers — what & why & done, who wants what, how to build — and sorting a statement to the one file that owns it.
The real triad
The Portal's first web rung specified by exactly three files. Each read by scope, audience, and
key sections — verbatim from f6.1.{md,stories.md,llms.md}.
The course itself
The same triad, one level up: chapter A4 specified by a4.{md,stories.md,llms.md}.
The course is a worked example of the artifact it teaches.
After A4.2, the next module — A4.3 · Anatomy of a spec — opens the first file and reads it section by section: Goal, Rationale, Scope, Deliverables, Invariants, and the Definition of Done. Return to the A4 module navigation to continue.
References
The sources behind the one-artifact-per-question split, and where it connects in the course.
Sources
- Adzic, G. — Specification by Example — the spec as the executable, shared truth the stories make concrete.
- Cohn, M. — User Stories Applied — the stories file as the user's side of a specification.
- Agile Alliance — User-story template (Connextra) — the "as a … I want … so that …" form the stories file is built from.
Related in this course
- A4.2.1 · Which question?
- A4.2.2 · The real triad
- A4.2.3 · The course itself
- A4 · The spec layer — the chapter.
- A0.2.2 · The four artifacts — the per-rung artifacts the triad is the core of.
- F6 · The Portal on the web (Phoenix) — the chapter whose F6.1 triad is the worked example.