Which question?

Each file in the triad answers one question, and only one. Fix the three questions first, then a statement sorts to the file that owns it.

A rung's specification says three different things to three different readers: what we build, why, and when it is done; who wants it, and how we will know; and how an agent builds it, with the gates. Select a question on the right and watch the candidate files collapse to the one that answers it.

The three questions Sort a statement On the Portal References

One question, one file · the candidates collapse

Question: what & why & done. One file answers it: fN.M.md — the spec (on F6.1, f6.1.md). For humans (author, reviewer). The other two files answer other questions; this one is not crammed with them.

Three questions, three readers

A specification of a rung is not one statement of intent — it is three, each shaped for a different reader and answering a different question. Naming the three questions first is what lets every later sentence find its file.

The first question is what & why & done: the contract. It states the goal, the rationale, the scope, the deliverables, the invariants, and the Definition of Done — read by an author and a reviewer. The second is who wants what, and how we'll know: the user's side, written as Connextra stories with Given/When/Then acceptance — read by product and QA. The third is how to build it, with proof gates: the agent brief, with references, requirements, the execution topology, and a runnable prompt — read by a coding agent. A statement belongs to exactly one of the three.

what & why & done: The contract. fN.M.md — Goal, Rationale, Scope, Deliverables, Invariants, Definition of Done. Audience: humans (author, reviewer).
who wants what: The user's side. fN.M.stories.md — Connextra stories, Given/When/Then, INVEST + the invariant each story encodes, the Coverage line. Audience: humans (product, QA).
how to build: The agent's brief. fN.M.llms.md — References, Requirements, Execution topology, Agent stories, the implementation prompt. Audience: a coding agent.
one statement, one file: A sentence answers one question, so it lives in one file. Crammed together, the contract drowns in build steps and the stories drown in references.

The triad answers what, who, and how — never two at once in one file. The next section sorts real statements to prove the partition holds.

Sort a statement to its file

If each statement answers exactly one question, then sorting is mechanical: read the statement, name the question, and the file follows. Below are five real statements from the Portal's first web rung — an invariant, a story, a deliverable, an acceptance line, and a requirement. Select one and the readout names the file that owns it and why.

Watch what does not happen: no statement lands in two files. An invariant is a property — it is .md, never a story. A Connextra "as a visitor…" is .stories.md, never the brief. A "read the endpoint docs first" is .llms.md, never the contract. The partition is what keeps each file readable for its one audience.

Pick a real F6.1 statement · its file follows

"PortalWeb calls only the Portal facade and renders only the closed %Portal.Error{} set" → answers what is done (an invariant) → lives in f6.1.md. A property, not a scenario; not a story, not a build step.

Read the statement, name the question, the file follows — an invariant to the spec, a story to the stories, a requirement to the brief, with no overlap.

The questions on the Portal

On the Portal — the learning platform this course builds — the first web rung is F6.1 · Bootstrap the Phoenix Portal. Its three questions are answered by three files. f6.1.md states what is built and when it is done: a deliverable such as F6.1-D6, "a liveness route returning a 200 without touching the domain", and an invariant such as F6.1-INV1, the master rule. f6.1.stories.md states who wants it: F6.1-US2, "as a visitor, I want to open a course page". f6.1.llms.md states how to build it: F6.1-R1, the endpoint requirement, traced back to its story.

Each line below carries its question as a comment and its file as the destination. No line answers two questions; that is what lets a reviewer read the contract without wading through build steps, and an agent read the brief without re-deriving the stories.

# A rung is specified by three files — one question each. (markdown spec text, not code)
# what & why & done  → the spec      f6.1.md         # F6.1-D6: a /health route returning 200; F6.1-INV1: the master invariant
# who wants what       → the stories   f6.1.stories.md # F6.1-US2: "as a visitor, I want to open a course page"
# how to build it      → the agent brief f6.1.llms.md  # F6.1-R1: PortalWeb.Endpoint as the outermost plug [US: F6.1-US1]

# A statement answers one question, so it sorts to one file. The partition is the discipline.

The principle

A statement answers one question, so it lives in one file. Sorting is mechanical: name the question, the file follows — the contract, the stories, or the brief.

On the Portal

F6.1 sorts cleanly: F6.1-INV1 to f6.1.md, F6.1-US2 to f6.1.stories.md, F6.1-R1 to f6.1.llms.md — every id to exactly one of the three.

One question per file: the spec says what is done, the stories say who wants it, the brief says how to build it — and a statement sorts to exactly one.

Recap — name the question, find the file

A rung's specification answers three questions, each for a different reader: what & why & done (the spec), who wants what (the stories), and how to build with proof gates (the brief). Every statement answers one of the three, so sorting a statement to its file is mechanical and the partition has no overlap. With the questions named, the next dive opens the three real files on the Portal and reads each one.

Next in A4.2: A4.2.2 · The real triad — the Portal's F6.1 specified by exactly f6.1.md / f6.1.stories.md / f6.1.llms.md, read by scope, audience, and key sections.

References

The sources behind the one-question-per-file split, and where it connects in the course.

Sources

Adzic, G. — Specification by Example — the spec as the executable contract 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 a story sorts into the stories file.

Related in this course

A4.2 · The triad — the module hub.
A4.2.2 · The real triad — the next dive.
A4.2.3 · The course itself — the same triad, one level up.
A4 · The spec layer — the chapter.
A0.2.2 · The four artifacts — the per-rung artifacts the triad is the core of.
A1.04 · Two layers — the spec is the fine layer the triad lives in.
F6 · The Portal on the web (Phoenix) — the chapter whose F6.1 triad is the worked example.