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.

1. Bar — one sentence: what "shippable" means for this surface. The north-star "done." 2. Dimensions — the few axes "good" decomposes into (correctness, idempotency, auditability, security, latency, recognizability…). Keep it short; these are the quality factors, not a feature list. 3. Floors — the minimum on each dimension with how it's measured (a floor without a measurement method is useless: "p95 < 200ms, measured via X"). The gate, not the ceiling — passing the floor licenses ship, not perfection. 4. Oracle — the independent verifier: what runs, who judges, and why it can't be gamed (maker ≠ judge). Pick the pattern that fits the surface: property tests or a staging run against forked state (objective surfaces); a deterministic simulator over fixed golden/archetypal inputs whose emitted trajectory a domain expert reads (pure engines — the inputs are fixed, so tuning to flatter one case visibly shifts the others); a blind human-judge quorum — fresh-context judges, ideally across vendors, naming the artifact with no context (subjective/taste surfaces, where no automated check can decide). For live systems the oracle extends past ship into telemetry — the prod signals that confirm it stays good. 5. Never — outcomes that are always a fail regardless of everything else (the safety invariants / "never events"). Concrete and absolute. 6. Decisions — calls already made, the tradeoff/priority policy ("security > latency; security can force a redesign, latency cannot"), and assumptions, so the agent never re-asks. This section grows: every answered question becomes a permanent entry. This is where mid-loop questions go to die. 7. Boundary — what requires the human: publish, biometric, live secrets, and genuine unknowns. Naming it tells the agent exactly what it may and may not do unattended.

Show, don't just tell. Any slot that is ambiguous earns a concrete instance — a golden example and/or an anti-example. Agents ground on exemplars; the Never list and the Oracle especially benefit.

Governance preamble

Open every brief with a one-line law statement, e.g.:

Law doc for <surface>, present-tense, no narrated history — git is the changelog. Amend Decisions and Boundary only with human confirmation; log the rationale. Dated working memory lives in DELTA.md / DEVIATIONS.md beside this file.

Authoring rules

• Match the house first. If the repo already has ratified briefs, copy their shape — section names, voice, any closing coda — over this skeleton. Consistency across the brief set beats the generic template; the seven concerns are the fallback when no house dialect exists yet. A reviewer judges a brief against the house dialect, and must not reject it for matching the repo's own law.
• Evidence-based. Ground Dimensions and Floors in the real surface; cite reference exemplars. Do not invent thresholds, signals, or behaviors.
• The oracle must be independent. Maker ≠ judge for any subjective dimension. Name why it can't be gamed — without independence the gate is theater.
• Floors are gates, not ceilings. A passing artifact may still owe refinement; say so. Never weaken a floor to pass a gate — an infeasible item gets the nearest-feasible alternative plus a DEVIATIONS.md entry, and the gap stays on record.
• Calibrate claims to enforcement. Match absolutist words ("never", "cannot") to what the oracle actually proves. Overclaiming invites reject cycles.
• Parsimony. Few, well-crafted floors that cover the cases beat a long brittle list. The brief is read every loop; every line earns its place.
• Mutation policy. Do not edit Decisions or Boundary without explicit human confirmation. When brief/implementation drift is found, surface it — the human decides.

Lifecycle

• Creation. When work begins to loop or the cost of being wrong is high. Draft the seven slots; the human ratifies. The harness is built to run the Floors; the Oracle is wired before iteration starts (harness-first).
• Maintenance. The Decisions section grows as questions are answered — every AskUserQuestion that should never recur becomes an entry. Floors tighten as the bar rises (rewrite as if always true). Cross-check the brief against the implementation whenever both are in context; surface drift.
• Retirement. When a surface is removed, remove or archive its BRIEF.md. Do not leave a stale law describing deleted behavior.

How the brief drives the loop

The brief is inert until it runs:

1. The harness runs the Floors and emits pass/fail with evidence (cheap, fast, fail-closed). 2. The oracle judges the subjective Dimensions independently. 3. The loop iterates act → verify → orient → decide until every Floor passes, or terminates as a bounded, honest blocked (with evidence and a proposed path). 4. Presence axis: attended, the human may opt out of ceremony for trivial work; unattended, the brief + harness are the only backstop — rigor is maximal and the Boundary (publish, secrets, biometric) is never crossed by the loop.

References

• template.md — the blank seven-concern skeleton, copy-paste ready when no house dialect exists yet; if the repo already has briefs, mirror those instead.
• example-payments.md — a filled brief for a money-transfer flow: the objective archetype, where floors are machine-checkable and the oracle is property tests + staging. The subjective/taste archetype — a visual or design surface whose bar is "elegant, calm, recognizable" and whose oracle is a blind human-judge quorum (maker ≠ judge) closing on a culminating "Final acceptance" frame — is the harder, more common product case; build its oracle from the blind-judge pattern in the Oracle slot.

BRIEF — peer-to-peer transfer flow (worked example)

Illustrative filled brief for a money-transfer surface — the seven slots on a non-visual,

high-stakes informatics system. Content here is illustrative, not a real system spec.

Law doc for the transfer flow, present-tense, no narrated history — git is the changelog. Amend

Decisions and Boundary only with human confirmation; log the rationale. Dated working memory

lives in DELTA.md / DEVIATIONS.md beside this file.

Bar

A transfer settles exactly once, is fully reconstructable from the audit log, and never moves funds the sender did not authorize — or it does not ship.

Dimensions

• Correctness — balances and ledger entries are right for every path, including partial failure.
• Idempotency — a retried or duplicated request never double-moves funds.
• Auditability — every state transition is logged with enough context to reconstruct it.
• Security — only an authenticated, authorized sender can move their funds; inputs are validated.
• Latency — the user gets a confirmed/pending state fast enough to trust the action.

Floors

Oracle

• Pre-ship: property + integration suite in CI (the independent judge for Correctness/Idempotency);

a fresh-context reviewer who did not write the change reviews the AuthZ matrix and the ledger math; a staging run against forked production state exercises the happy path and the partial-failure path.

• Post-ship (live): dashboards + alerts on ledger-imbalance count (must stay 0), duplicate-effect

rate, authz-denial anomalies, and p95 latency. These are the continuing oracle for a live system — the harness was the proxy; production is the final gate.

Never — instant fail

• Funds move without a matching, authorized request (silent or unauthorized transfer).
• A ledger that can go negative, or whose entries don't sum to a conserved total.
• A state transition that lands without an audit event.
• An unbounded retry, or a retry without an idempotency key.
• A secret in a log line, error message, or trace.
• Weakening a floor, or shipping a failing path without a DEVIATIONS.md entry and a replacement.
• Asking the human to lower the bar.

Decisions

• Priority / tradeoffs: correctness > security > auditability > latency. Correctness and security

may force a redesign; latency may not. Never trade an audit event for speed.

• Assumptions: the ledger is the source of truth, not the cache; the message bus is at-least-once

(hence idempotency keys are mandatory, not optional).

• Idempotency key is required on every mutating request; absent key → reject, don't guess. (illustrative)
• Pending state is shown optimistically only after the request is durably enqueued, never before. (illustrative)

Boundary — requires the human

The loop never crosses these; they batch to the human handoff.

• Publish: deploy to production, database migrations, feature-flag flips that expose the flow to users.
• Credentials: any live-key access (production DB, signing keys, KMS) — the loop verifies against

staging/forked state, never production secrets.

• Direction: limit policy, fee structure, regulatory/compliance calls — accumulate as

blocked: needs N decisions rather than guessing.

BRIEF — product landing-page hero (worked example)

Illustrative filled brief for a subjective/taste surface — the seven concerns where the bar is

"premium, clear, calm" and no automated check can decide quality, so the oracle is a blind

human-judge quorum. The objective sibling is example-payments.md. Content here is illustrative,

not a real system spec. This example also shows the optional Final-acceptance coda — a

culminating whole-surface test that restates the Boundary as a gate.

Law doc for the landing hero, present-tense, no narrated history — git is the changelog. Amend

Decisions and Boundary only with human confirmation; log the rationale. Dated working memory

lives in DELTA.md / DEVIATIONS.md beside this file.

Bar

A first-time visitor understands what the product does and feels it is a real, premium product within five seconds — calm, clear, on-brand — or it does not ship.

Dimensions

• Clarity — a stranger can say what the product does and who it's for, unprompted.
• Credibility — it reads as a real, trustworthy product, not a template or a generic demo.
• Calm / restraint — one focal message; nothing competes; premium is quiet, never loud.
• Brand fidelity — type, color, and spacing resolve to the brand system; no off-system improvisation.
• Performance & access — it loads fast and is legible and operable for everyone (the objective floor under a visual surface).

Floors

Oracle

The maker may not judge first impressions — you cannot un-see your own copy, so your read is permanently biased (the exact failure the oracle exists to defeat).

• Subjective gate — blind human-judge quorum. Five fresh-context judges, ideally across

different people/vendors who have never seen the page, each given only the screenshot and the clarity + credibility questions — no product context. Quorum, not one opinion; diversity in the panel defeats a single idiosyncratic taste and cannot be talked around.

• Objective floors run in CI (Lighthouse, axe, token-lint) — fail-closed, no human in the path.
• Reference-anchored. Place the captured hero beside the brand's reference frames and the top

three admired peers; write DELTA.md — the ten most significant gaps ranked by impact; fix the top three; re-capture. The round closes only after the re-capture.

• Post-ship (live). The oracle extends into telemetry: hero bounce rate, scroll-past rate, and

CTA click-through are the continuing signal that the first impression holds. The judge panel was the proxy; the live audience is the final gate.

Never — instant fail

• It reads as a template or generic AI output — interchangeable with any other product's page.
• A stranger cannot say what the product does after five seconds.
• More than one thing competes for the eye; any autoplaying or looping motion; anything that

performs instead of communicates.

• An off-brand color, typeface, or spacing value; an improvised token.
• Text below AA contrast, or content that fails keyboard / screen-reader operation.
• A claim the product can't back — a fabricated testimonial or invented metric.
• Weakening a floor, or shipping a failing element without a DEVIATIONS.md entry and a replacement.
• Asking the human to lower the bar.

Decisions

• Priority / tradeoffs: clarity > credibility > brand-polish > visual flourish. Clarity and

access may force a redesign; a flourish may not. Between two designs, ship the calmer, clearer one — restraint beats spectacle.

• Assumptions: the brand token system is the source of truth, not a local design choice; mobile

is the primary viewport.

• Copy is owned by the brand voice guide; the hero never invents claims. (illustrative)
• One hero, one CTA; secondary actions live below the fold. (illustrative)

Boundary — requires the human

The loop never crosses these; they batch to the human handoff.

• Publish: pushing the page live, DNS/CDN changes, anything visitor-facing.
• Brand authority: changing a brand token, the positioning statement, or the core claim — the

loop proposes, the brand owner decides.

• Tie-break & direction: when the blind quorum splits, the human breaks the tie; genuine

brand-direction unknowns accumulate as blocked: needs N decisions, never guessed.

• Real-audience validation beyond the proxy judges (actual target-audience testing) is the

human's call.

---

Final acceptance — the five-second test

Capture the hero exactly as a first-time visitor meets it on a mid-tier phone. Show it to someone who has never seen the product for five seconds, take it away, and ask: what does this do, and would you trust it? If they answer the first and lean yes on the second — with no template smell, no second focal point, no off-brand note — the surface has done its job. Until then, iterate.

Then the brand owner looks; their read is the gate after the frame. And the gate after the owner is the real one: a stranger in the target audience who stays past the fold.

BRIEF — <surface name>

Law doc for <surface>, present-tense, no narrated history — git is the changelog. Amend

Decisions and Boundary only with human confirmation; log the rationale. Dated working memory

lives in DELTA.md / DEVIATIONS.md beside this file.

Bar

<One sentence: what "shippable" means for this surface. The north-star "done.">

Dimensions

The few axes "good" decomposes into. When this document doesn't cover a decision, resolve it in favor of these.

• <Dimension 1> — <what it means here>
• <Dimension 2> — <…>
• <Dimension 3> — <…>

Floors

The minimum on each dimension, with how it's measured. The gate, not the ceiling.

Oracle

The independent verifier — what runs, who judges, and why it can't be gamed (maker ≠ judge).

• Pre-ship: <the harness/judge that runs the Floors before ship>
• Post-ship (live systems only): <the telemetry/signals that confirm it stays good>

Never — instant fail

• <Outcome that is always unacceptable, regardless of everything else>
• <…>
• Weakening a floor, or removing a failing item without a DEVIATIONS.md entry and a replacement.
• Asking the human to lower the bar.

Decisions

Calls already made, so the agent never re-asks. This section grows — every answered question becomes a permanent entry. Include the tradeoff/priority policy and standing assumptions.

• Priority / tradeoffs: <e.g. "security > latency; security may force a redesign, latency may not">
• Assumptions: <standing assumptions about the environment; revisit if they break>
• <Decision> — <the call, and one line of rationale> (<date>)
• <Decision> — <…> (<date>)

Boundary — requires the human

The loop never crosses these; they batch to the human handoff.

• Publish: <push / PR / merge / deploy / release>
• Credentials: <live secrets, biometric-gated actions>
• Direction: <genuinely undecided product/architecture calls — accumulate as blocked: needs N decisions>