brief-best-practices

What a brief is

A BRIEF.md is the verifier's spec — the codified taste that says what "good" means for a surface, so an agent can verify its own iterations and run a loop without guessing or interrupting. Where SPEC.md is the contract (what to build: REQ-*, invariants), the brief is the bar (what "good" is, and who judges).

It is the BRIEF rung in the stack VISION → SPEC → BRIEF → HARNESS → LOOP → BOUNDARY: the brief is what makes the autonomous loop trustworthy, because the harness runs the brief's floors and the oracle judges against them.

When to author one

Author or update a brief when work will loop (you'll iterate against it more than once) or when the cost of being wrong is high. Trivial, one-shot changes need no brief — do not manufacture ceremony. Build cheap verifiers freely; propose an expensive brief+harness before investing in it.

Naming & placement

Always BRIEF.md, colocated with the surface it governs: root for project scope, apps/foo/BRIEF.md, packages/bar/BRIEF.md, or a docs subtree (e.g. docs/toys/BRIEF.md). Dated working memory lives beside the brief, never inside it — e.g. DELTA.md (per-round gaps, ranked) and DEVIATIONS.md (infeasible → nearest-feasible, logged). The brief is present-tense law; git is the changelog.

The seven slots (required concerns, adaptable shape)

The contract is that all seven concerns are present, in this order — not a fixed ##-count. The content adapts to the domain (a payments flow, an indexer, a CLI, a 3D toy); the concerns never change. A domain may split a concern across sections, or close with a culminating "Final acceptance" coda: one whole-surface test that restates the Boundary as a gate ("then the human ships it; the real gate is a user who…"). That coda is a framing of Boundary + Oracle, not an illegal eighth slot. The rule is don't drop a concern — not don't add a heading; still, keep sections as few as the content allows. Absent a house dialect (see Authoring rules), these seven are the skeleton.