A5.2 · module hub
References and requirements
The brief's first two parts: the sources an agent reads, then the numbered, testable statements it satisfies — each one a check, not a wish.
An agent brief opens with its references — the exact sources read before any
narrative. Its requirements come second: numbered, testable, each a single statement traced to the user
story it serves. The Portal's real f6.1.llms.md carries six references and eight
requirements, F6.1-R1 through F6.1-R8. Pick a part on the
right to read what each delivers; three dives below take references, numbered requirements, and
traceability in turn.
The brief's first two parts · pick one
A requirement names a check, or it is a wish
References tell the agent what to read; requirements tell it what to produce. The difference between a
requirement and a goal is one thing: a requirement names a check. f6.1.llms.md
numbers eight requirements, F6.1-R1 through F6.1-R8, and
every one carries a check kind — the app boots, a route renders, a grep is empty, the endpoint
restarts. A statement with no check — “keep the boundary clean” — reads like a
requirement but cannot be satisfied or reviewed, because there is nothing to run.
The figure holds the eight requirements as a grid, each labelled with its check kind. Toggle the second
control to blur F6.1-R7 — the static-grep master invariant — into a
vague goal, and watch the testable count drop from eight to seven. These requirements are built in the
Portal's web bootstrap, the request lifecycle of the companion
course.
The eight requirements · testable or a wish
# F6.1-R7 — the master invariant, statically checkable grep -rE "Portal\.Engine|Repo|GenServer\.call" apps/portal_web/lib/ # => (empty)
The principle
References first, then numbered testable requirements; a requirement names a check or it is a wish. A goal cannot be satisfied or reviewed, because there is nothing to run.
On the Portal
f6.1.llms.md lists the exact sources, then F6.1-R1…R8,
each a single checkable statement — R6: GET /health returns 200
“ok”; R7: an empty invariant grep.
A requirement the agent can run a check against is buildable; one it can only interpret is not.
The three dives
Each dive takes one idea from the two parts, in the arc read → number → trace: the references the agent reads first, the numbered requirements it satisfies, and the trace that ties each one to the story it serves. Read them in order — A5.2.1 starts.
References first
Every source the agent reads, before any requirement — framework docs, the upstream contract it must not modify, the design system, the spec system.
Numbered requirements
F6.1-R1…R8: numbered, testable, each one a single checkable
statement the agent satisfies and the reviewer runs.
Traceability
Each requirement names the story it serves and the check it satisfies; an untraced requirement is flagged — work no story asked for.
After A5.2, the next module — A5.3 · Execution topology — takes the third part of the brief: the runtime shape, the build-order task DAG, and the file list. Return to the A5 module navigation to continue.
References
The conventions this module draws on for writing machine-readable references and traceable, testable requirements, and where the requirements it grounds on are built in the course.
Sources
- llmstxt.org — The /llms.txt convention — a links-first, machine-readable document format an agent reads before prose; the form the references part takes.
- Cohn, M. — User Stories Applied — testable acceptance criteria traced to the story they serve, the discipline behind a numbered requirement.
- Hunt, A. & Thomas, D. — The Pragmatic Programmer — specify only what is testable, and make every requirement a check rather than a wish.
Related in this course
- A5.2.1 · References first
- A5.2.2 · Numbered requirements
- A5.2.3 · Traceability
- A5.1 · Writing for an agent — the convention these parts take.
- A5 · The agent brief
- Companion · The request lifecycle (F6.1) — where
F6.1-R1…R8are built. - Companion · Phoenix (F6) — the chapter whose
f6.1.llms.mdthis module grounds on.