writing-codex-briefs

# Writing Codex Briefs Codex sees **zero** chat history. The brief is the only channel. Anything not in it does not exist for Codex. ## The Acceptance File — `.codex/ACCEPTANCE.md` Written and committed BEFORE dispatch. This is the frozen bar the judge will enforce. ``` GOAL: <one sentence: what "done" means> CHECKS (all must pass, exact commands): - `<command>` exits 0 and prints <expected> - `<build/typecheck command>` exits 0 - `<specific test command>` exits 0 CONSTRAINTS: - Only edit <files/dirs>. Do not modify <test files / this file / unrelated code>. ``` **Writing checks that protect you** (the judge is only as strong as these): - Prefer commands with **exit codes** over "the code should look right". - Include at least one check that **fails before the work is done** (red → green) — a check that passes on the untouched repo proves nothing. - Name the *specific* tests, not "run the tests" (slow suites make the judge cry wolf; flaky checks are worse than none). - Vacuous bars ("typecheck passes") let bad work through with a green light. Ask: *could a lazy stub pass these checks?* If yes, tighten them. ## The Brief ``` GOAL: <same one sentence — must match ACCEPTANCE.md> CONTEXT: <repo path, key files, constraints — everything Codex needs, it cannot ask you> DO: <numbered, concrete steps> VERIFY: <run the exact CHECKS above and show their real output> REPORT: <what to return: diff summary + which checks passed> DO NOT: commit anything; touch .codex/ACCEPTANCE.md; edit unrelated files; delete or weaken tests; add silent fallbacks or fake/stubbed results. ``` The `DO NOT` block is mandatory and always includes those five items — they are the exact ways executor models paper over failure. ## Common Mistakes - **Context by reference** ("as discussed above") — Codex has no "above". Inline it. - **Goal drift** — brief GOAL ≠ ACCEPTANCE GOAL means the judge enforces a different bar than Codex aimed at. - **Kitchen-sink briefs** — one dispatch, one goal. Two unrelated goals = two dispatches.