Giving Codex a Clear Definition of Done

"Fix the bug" and "fix the bug so the reported error no longer occurs and the existing test suite still passes" describe the same task with wildly different amounts of room for a session to declare victory prematurely. The gap between those two instructions is, in practice, the gap between a task that gets genuinely finished and one that gets abandoned somewhere in the middle wearing the appearance of completion.

Why vague instructions produce vague endings

A model asked to do something without a stated success criterion has to invent one, and it will — usually a reasonable-sounding one, just not necessarily the one you had in mind. "Improve the error handling here" might get answered with a genuinely improved but incomplete pass, because "improve" has no natural stopping point the model can check itself against. A session that doesn't know what done looks like can't reliably tell you it's done; it can only tell you it's stopped working on it for now.

What a concrete definition of done actually looks like

The strongest definitions are checkable, not just describable: a specific test that should pass, a specific error message that should no longer appear, a specific behavior that should be reproducible on demand. "The existing test suite passes and this new test, covering the reported edge case, also passes" is a definition of done a session can verify against itself, not just assert about itself — and that distinction is the entire value of stating it this way.

Definition of done versus scope

These are related but separate things worth stating both of, not conflating into one instruction. Scope answers "what am I allowed to touch" — which files, which parts of the system are fair game. Definition of done answers "how do I know I'm finished" — what observable state means the task is actually complete. A session with clear scope but no definition of done can wander indefinitely within its allowed boundary without ever confidently stopping; a session with a clear definition of done but unclear scope can solve the right problem in the wrong place.

Why this matters more for agentic sessions than for a single prompt

A one-shot prompt either gets a good answer or it doesn't, and you find out immediately by reading the response. An agentic session iterating over multiple turns needs an internal stopping condition, because it's the one deciding, turn to turn, whether to keep going or declare the task complete. Without a concrete definition of done, that internal decision is made on vibes — "this looks reasonably finished" — which is exactly the judgment most likely to diverge from what you actually wanted, especially on a task with real edge cases a superficial pass wouldn't surface.

Stating the definition of done before the task, not after

It's tempting to let a session start working and clarify "what done means" once you see where it's headed. That ordering wastes the exploration a session does before you've told it what target to aim at — work that might need redoing once the actual target becomes clear. Stating the definition of done up front, even roughly, gives every turn from the first one onward something concrete to steer toward, rather than only the later turns once you've finally articulated it.

When "done" genuinely can't be fully specified in advance

Not every task has a crisp, checkable definition of done available before you start — genuinely exploratory work, where you're not sure what a good answer even looks like until you see some options, is a real category this doesn't neatly apply to. For that kind of task, it's worth being explicit that you're in exploration mode rather than execution mode, and treating the session's output as a starting point for your own judgment rather than expecting it to self-certify completion the way a well-specified task can.

A habit worth building for every non-trivial task

Before starting a session on anything beyond a truly trivial change, spend the ten seconds it takes to actually write out what "done" means for this specific task — a test, an error message, a behavior. It's a small habit, and the return on it compounds specifically on the tasks that would otherwise have been hardest to tell, after the fact, whether they were actually finished or just stopped.

Definition of done for tasks with no automated check available

Not every task has a test suite or an error message to check against — a lot of real work is genuinely subjective, like improving how a piece of documentation reads or adjusting the tone of an error message shown to users. For these, the definition of done still benefits from being as concrete as the task allows: naming specific criteria ("a new contributor unfamiliar with this module should be able to follow the setup steps without needing to ask a question") gets you further than "make this clearer," even without a script that can verify it automatically. The goal is reducing ambiguity, not eliminating it entirely where it genuinely can't be eliminated.

Revisiting the definition of done mid-task

Sometimes a definition of done stated at the start turns out to be wrong once real work reveals something you didn't anticipate — an edge case that makes the original success criterion insufficient, or a constraint that makes it unreachable as originally stated. Treating the definition of done as revisable, rather than fixed the moment it's written, matters here the same way a revisable task plan matters elsewhere: the value is in having a concrete target to check against at any given moment, not in that target being permanently unchangeable once set.

What a missing definition of done costs beyond the immediate task

Beyond the risk of a single task ending prematurely, a pattern of vague instructions across many tasks trains a kind of learned vagueness into how a team works with Codex generally — if "done" is never stated precisely, sessions never get calibrated feedback about what precision actually helped, and the habit of writing looser instructions compounds across every future task. Treating a clear definition of done as a standard practice, not a special step reserved for unusually important tasks, is what actually breaks that pattern.