---
name: ccplugins/writing-codex-briefs
source: https://app.decimal.ai/s/ccplugins-writing-codex-briefs@1/SKILL.md
source_sha256: 826c4af326a2
---

# 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.