Brief the rung

Briefing a rung is A5.1 through A5.5, run once on a real slice. The slice here is F5.2 — model the Portal domain, the rung that turns seven entities and three bounded contexts into compiling modules over the F4 store. Its brief, f5.2.llms.md, is five parts, each filled from the rung's spec and stories.

The references come first, links first: Elixir structs and @enforce_keys, typespecs, “make illegal states unrepresentable,” the F0 design system, and the upstream Portal.Store (get/2, all/2, put/1) and Portal.ID. Then the requirements — F5.2-R1 through F5.2-R6, numbered and testable. Then the topology — plain modules, no new processes, and the task DAG T1→T6. Then the agent stories (F5.2-AS1–AS3), each a Directive and a gate. Last, the implementation prompt that runs the stories in task order and ends on the verification gates.

The hero figure stepped through those five in order. The point of the order is that each part rests on the one before it: requirements cite references, the topology orders the requirements, the stories close the tasks, and the prompt runs the stories. The brief is ready only when all five are present.

A brief is complete when every one of the five parts is present — not most of them, all of them. The completeness check is the test the Operator runs before handing the brief to an Author: read the five parts, confirm each is filled, and only then run it. Drop a part and the brief still reads like a brief, but it leaves a decision open the Author will fill on its own.

Toggle the figure below between the full F5.2 brief and the same brief with the execution topology removed. With all five present, the brief is runnable; drop the topology and it is incomplete — the Author has the requirements but no build order and no file list, so it would order the build itself and touch files the brief never named.

The F5.2 brief, f5.2.llms.md, is the rung the workshop briefs first. Its references open with structs and @enforce_keys, typespecs, and the upstream Portal.Store and Portal.ID. Its requirement F5.2-R1 fixes the seven entity structs, each enforced; its requirement F5.2-R3 — the one the workshop writes — fixes the documented public API per context, each function with an @spec, every other function private. The three bounded contexts the brief defines are taught in the companion course at /elixir/phoenix/contexts.

# f5.2.llms.md — F5.2-R3 (verbatim): the part the workshop writes
#
F5.2-R3 — the documented public API per context, each function with an @spec, all other
  functions private:
  Accounts.user/1 :: {:ok, %User{}} | :error;
  Catalog.course/1, Catalog.lesson/1 likewise;
  Learning.enroll/2 :: {:ok, %Enrollment{}} | {:error, atom};
  Learning.courses_of/1 :: [%Enrollment{}]. [US: F5.2-US3]
#
# F5.2-R1: seven entity structs (User, Session, Course, Lesson, Page, Enrollment,
#   Progress), each @enforce_keys + defstruct + @type t; id/*_id are branded-id strings;
#   @enforce_keys lists every field except progress (default 0, type 0..100). [US: F5.2-US1]
#
# Topology: plain modules over the F4 store, no new processes.
#   T1 structs → T2 contexts → T3 public APIs → T4 reads + enroll → T5 typespecs → T6 verify
# Agent stories: F5.2-AS1 (entities that cannot be built incomplete), AS2 (bounded
#   contexts), AS3 (public APIs over the store) — each a Directive and an Acceptance gate.

The enroll write the brief specifies mints a branded id — Portal.ID.generate("ENR") — builds an %Enrollment{}, and stores it with Portal.Store.put/1. The brief names all of that exactly, so the Author writes the function rather than choosing its shape.

Briefing a rung is A5.1 through A5.5 applied once: fill the references, the requirements, the topology, the agent stories, and the implementation prompt for one specified slice — here, F5.2. A brief is complete only when all five parts are present; drop one and the Author fills the gap with a decision the Operator should own. With the F5.2 brief assembled and complete, the next dive runs it — the implementation prompt, in task order, watching its gates.

Primary sources for writing a machine-readable brief and pinning every decision the builder must not invent, and where the rung this dive briefs and the companion course that builds it are defined.