References first

The first part of the brief is the reading list. Before any requirement, References front-loads every source the agent reads — links first, each one named to a single reading.

A requirement does not stand alone; it reads a source. References gathers those sources and places them ahead of every requirement, so the agent reads what it needs before it builds. The Portal's real f6.1.llms.md opens with six such entries — framework hexdocs, the design system, and the upstream Portal facade contract that is also a constraint. Toggle the figure on the right to sort those references by kind: not every reference is the same shape.

The reading list On the Portal Read-order coverage References

The six references the agent reads first · sort by kind

f6.1.llms.md — references the agent reads first: 6, across 3 kinds — 4 framework docs, 1 design system, 1 upstream contract. The contract is a reference that is also a constraint: it pins what the agent must not change.

The reading list

References is the first of the brief's five parts. It is a reading list: every source the agent works through before it reads a single requirement, placed links first so the agent never has to hunt for one. A4's spec says what to build and how to know it is right; it does not gather the sources the build reads. The brief does, and it does so first.

Not every reference is the same shape. Most point at a framework doc the agent calls — the Phoenix endpoint, the router, the controllers, the Plug stack. One points at the design system the output renders in. And one is different in kind: it is a constraint as much as a source. The “Upstream contract (do not modify)” entry names the Portal facade and pins what the agent must not change — the return shape of courses_of/1, the closed error set, the supervision tree it inherits from F5. A reference that is a constraint front-loads a boundary, not only a doc.

The principle

Every requirement's source belongs in References, read before the requirement. The reading list is front-loaded so the agent reads what it needs, then acts — it never improvises a source.

On the Portal

f6.1.llms.md's References carries the Portal facade contract that R4 and R8 depend on, so the agent reads the contract before it builds the controller and its fail-soft path.

This dive opens A5.2: References first, then numbered requirements (the next dive), then the trace from each requirement to the story it serves. The endpoint the first reference points at is built in the companion course's Phoenix endpoint lesson.

On the Portal — the contract that is also a constraint

The Portal's web bootstrap, f6.1.llms.md, opens its ## References with six entries, links first. Four are framework hexdocs (endpoint, router, controllers, Plug). One is the F0 design system. The sixth is the upstream Portal facade contract, and it does double duty: it tells the agent where to read the facade and it pins what the agent must not modify.

# f6.1.llms.md — ## References (links first; six entries)
#   1 Phoenix endpoint   — the plug stack and socket/3       (framework)
#   2 Phoenix router     — pipeline, pipe_through, scope, get (framework)
#   3 Phoenix controllers— actions, render/3, put_status/2   (framework)
#   4 Plug              — Static, RequestId, Parsers, Session (framework)
#   5 F0 design system  — tokens, page anatomy, the A+ gates  (design)
#   6 Upstream contract (do not modify)                       (contract)
#
# The sixth entry, verbatim — a reference that is also a constraint:
  Upstream contract (do not modify). The Portal facade — query
    courses_of/1 :: {:ok, [%Enrollment{}]} (as-built and total / success-only:
    the wrapped list, no bare-list arm). The controller still pattern-matches the
    {:error, %Portal.Error{} = e} arm defensively, so the 422 render
    path exists and is unit-testable. The closed error set is
    %Portal.Error{code, message, field}.

Because that one reference carries the contract, the requirements that read it can stay terse. F6.1-R4 (the controller calls only Portal.courses_of/1; a domain error renders 422) and F6.1-R8 (an expected failure yields a 422, never a 500) both point back to entry six. Strip it from References and those requirements read no contract — the agent would build the controller and its error path blind.

References is the reading list; a requirement with no source on it is a requirement read blind.

Read-order coverage

A reading list earns its place by covering the requirements that follow it. Every one of F6.1-R1 through F6.1-R8 reads exactly one of the six References entries: the endpoint requirement reads the endpoint doc, the router and health requirements read the router doc, and the controller, boundary, and fail-soft requirements all read the upstream facade contract. When every requirement's source is on the list, coverage is complete.

Toggle the meter below between the full reference list and the same brief with the upstream facade contract dropped. With the full list, no requirement is left without a source. Drop the one contract entry and the requirements that read it — the controller (R4) and the fail-soft path (R8) among them — are stranded.

Does every requirement's source sit in References · drop a reference

Full references — requirements left without a source: 0 of 8. Every requirement reads a reference that is on the list, so the agent reads its source before it builds.

The principle

Coverage is the test of a reading list: every requirement's source must be present in References. A stranded requirement is one the agent reads with no contract behind it.

On the Portal

In f6.1.llms.md, R4 and R8 both read the upstream facade contract. Drop that one entry and the controller and its fail-soft path read no source — coverage fails before a line is written.

A complete reading list covers every requirement; the moment one reference is missing, a requirement is read blind.

Recap — references before requirements

References is the brief's first part: a links-first reading list of every source the agent reads before any requirement. The Portal's f6.1.llms.md front-loads six entries — four framework docs, the design system, and the upstream Portal facade contract that is also a constraint. Every requirement reads one of them, so coverage is complete; strip a reference and the requirements that cite it are read blind. The next dive turns to those requirements themselves — numbered, testable, each a single checkable statement.

Next in A5.2: Numbered requirements — F6.1-R1 through F6.1-R8, each a single, numbered, checkable line.

References

Primary sources for writing a links-first reading list and for grounding each requirement in a named source, plus where the Portal rung this dive grounds on is built in the companion course.

Sources

llmstxt.org — The /llms.txt convention — the links-first, machine-readable form a brief takes, with sources placed ahead of prose.
Cohn, M. — User Stories Applied — a story, and the requirement that serves it, is grounded in concrete sources rather than assumptions.
Hunt, A. & Thomas, D. — The Pragmatic Programmer — design by contract: name the source so the builder never has to guess it.

Related in this course

A5.2 · References and requirements — the module hub this dive opens.
A5.1.1 · Links first — why a brief front-loads its links at all.
A5 · Why a brief layer — the layer References is the first part of.
Companion · The request lifecycle (F6.1) — the rung whose f6.1.llms.md References block this grounds on.