Every reference exact

A5.1.1 settled the order: links first, the agent reads the sources before any narrative. This dive settles the links. A reference is exact when it names its target to a precision that admits one reading. “The facade” names a thing that could be any of several. “The Portal facade” narrows it to one module. Portal.courses_of/1 :: {:ok, [%Enrollment{}]} pins the function, its arity, and its return shape, so there is nothing left for the agent to choose.

The cost of a loose reference is not that the agent fails — it is that the agent improvises. Faced with two readings, it picks one, and the pick is a decision the brief was supposed to make. An exact reference removes the pick. The agent reads the one right thing and builds it; a loose one hands it a fork and hopes it chooses the branch the spec intended.

The Portal's real agent brief, f6.1.llms.md, carries one reference that is also a constraint — the upstream facade contract. It is the example to study, because it is named to a precision the agent cannot misread. Quoted verbatim from the brief's ## References block:

## References
# 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, and no {:error, %Portal.Error{}} producer —
# an unknown or malformed user id yields {:ok, []}). The controller still
# pattern-matches the {:error, %Portal.Error{} = e} arm defensively, so the 422
# render path exists and is unit-testable. And the closed error set
# %Portal.Error{code, message, field} with code in
# :already_enrolled | :course_not_found | :lesson_locked | :invalid_progress.

Read what the reference pins: the function (courses_of/1), the success shape ({:ok, [%Enrollment{}]}, total / success-only), the defensive arm ({:error, %Portal.Error{} = e} → a 422 render), and the closed code set. Requirement F6.1-R4 reads exactly this and builds the controller's two arms — the success list and the 422 error render — without inventing a third shape. The same contract is the controller's reference on the companion course: see the controller lifecycle for how the call is wired.

Now strip the contract to “render the user's courses, handle errors.” The function arity is gone, the return shape is gone, the error set is gone. The agent can still build the success arm — a list is a list — but the error arm has no shape to render and no closed set to match. It invents a %Portal.Error{} with fields that do not exist, or drops the arm. The interactive below counts the arms an agent can build at each level of precision.

The lesson lands on the Portal's real controller rung. The brief reference pins courses_of/1 to its exact return shape and the closed %Portal.Error{code, message, field} set; the controller reads it and renders, never guesses. The success tuple yields the index render; the defensive error tuple yields the 422 render of a struct whose fields are named, not invented. Because the reference is exact, the two arms are a transcription, not a design problem.

# f6.1.llms.md References — the exact contract the controller reads:
#   courses_of/1 :: {:ok, [%Enrollment{}]}   (total / success-only)
#   closed set: %Portal.Error{code, message, field}, code ∈ {:already_enrolled, ...}

# F6.1-R4 transcribes the two named arms — nothing invented.
def index(conn, %{"user_id" => user_id}) do
  case Portal.courses_of(user_id) do
    {:ok, courses} -> render(conn, :index, courses: courses)
    {:error, %Portal.Error{} = e} ->
      conn |> put_status(422) |> render(:error, error: e)
  end
end

Links first put the sources before the prose; exact references make those sources unambiguous. A reference is exact when it admits one reading — the function, its arity, its return shape, the closed error set — so the agent reads the one right thing and transcribes it. The Portal's f6.1.llms.md pins its facade contract this way, and the controller builds both arms without inventing a third. The closing dive collects the order and the precision into one form: the shape a whole machine brief takes.

Primary sources for writing a reference an agent reads once, and where it connects in the course.