Briefs

A brief is a self-contained scope-and-DoD contract — the fundamental unit of work in Assay. One agent must be able to execute it without reading the rest of the plan. Every field is designed so a script can check it.

Why briefs

When a fleet of agents does the implementation, work units written as prose in a task tracker fail silently. Dependencies written as "after the auth brief" break on a rename with no error. A brief is a machine-readable contract: typed IDs, explicit dependencies, a parseable Verify table. The form forces the structure that makes drift visible.

Anatomy of a brief

Every brief carries YAML frontmatter and a structured body. The frontmatter is the parseable record; the body motivates but never solely carries a fact a script needs.

Field	What it holds	Why it is there
`brief`	Typed ID: `stream/NN`	Links the brief to its stream README table row. Never a prose name.
`title`	One-line summary	Human-readable, for the board and Next-up display.
`wave`	Integer: 0 = no deps, N = deps in waves < N	Derived from the dependency graph. Lets the board schedule parallel work.
`depends` / `unblocks`	Typed ID arrays, mutual inverses	A typed ID survives renumbering and greps cleanly. No prose arrows.
`effort`	`S`, `M`, or `L`	Scheduling tier. S may run inline; M/L plan then dispatch to implementers.
`gate`	`model` or `human`	Derived from risk answers. Any yes in `risk:` forces `human`.
`risk`	Four booleans: regulatory, customer, irreversible, sensitive-data	Record all four. The gate is their conclusion — not a separate choice.
`sources`	Typed IDs: scoping docs, findings, intake entries	Provenance. An empty list is untraceable — no one can tell why the work exists.

Load-bearing facts live in islands, not prose. Frontmatter, tables, and Verify rows are the record. Prose motivates but never solely carries a fact a script or reviewer needs.

The Task section

The Task is the implementer's instructions: numbered steps, exact paths, specific actions. It is accompanied by a files: listing (exact paths — no repo exploration needed) and facts: (the 3–5 project facts required to execute, in key: value form). A brief that touches a shared value — a party, env var, config key, field meaning, wire format — enumerates every consumer under consumers: with a disposition (fixed-here / follow-up / out-of-scope).

The Verify table

Every brief carries a Verify table: a list of executable checks. Each row has a literal command and an expected exit code or output. A row without both is not a DoD item; it is a hope. Evidence over claims is the whole discipline, and it starts here.

For prose deliverables (docs, articles), Verify rows assert presence: a file exists, a section appears, a token is present. Quality is owned by the human review gate — presence gates do not prove quality, and claiming they do is the exact anti-pattern the system exists to catch.

Verify rows must be runnable by someone who did not do the work. The implementer runs them and fills Evidence. A non-implementer re-runs them on merged main to advance from implemented to verified. This is the independent re-execution check: no one assays their own metal.

Rules enforced by lint

Typed IDs only. References are stream/NN, F-NN, I-NN — never fuzzy names.
Self-contained. If executing needs knowledge from another brief, link it in facts: or state it in depends:.
Dependencies are typed and inverse. A brief in depends: must list this brief in its unblocks: (and vice versa).
Wave consistency. A brief at wave N must only depend on briefs at waves < N.
Provenance required. An empty sources: fails lint.
Gate derived from risk. A brief with gate: model and any risk yes fails lint.

Splitting and sizing

Briefs should be roughly equal-sized. A brief doing two distinct roles becomes two briefs. Rough test: if the Task needs more than about five steps or touches more than two subsystems, split at authoring time. Uneven briefs stall a wave and hide the real critical path.

← Back home