Codex Goals

OpenAI Codex Goals Best Practices

Reference for writing and managing Codex Goals — the persistent objective feature introduced in Codex 0.128.0. "Best practices" here means the patterns and anti-patterns that determine whether a Goal completes against the right evidence vs. silently against the wrong surface. Contains 31 rules across 8 categories, ordered by how much they affect whether a Goal completes correctly. Derived from the official OpenAI cookbook article "Using Goals in Codex".

When to Apply

Reference these guidelines when:

• Deciding whether a task warrants a /goal or a normal prompt
• Drafting or strengthening a /goal invocation
• Reviewing a Goal someone else wrote before activating it
• Debugging a Goal that completed against the wrong verification surface
• Setting up a research Goal where exact proof may not be available
• Managing Goal lifecycle (pause, resume, clear) across thread sessions
• Writing the iteration policy or blocked stop condition for a long-running Goal
• Diagnosing a Goal that hit its budget without completing

Rule Categories by Priority

Individual rule impacts are listed inline in the per-rule frontmatter.

Quick Reference

1. Goal Fit Decisions (CRITICAL)

• `fit-when-to-use` — Use a Goal When the Finish Line Is Clear but the Path Is Uncertain
• `fit-three-required-properties` — Require Three Properties Before Setting a Goal — Durable Objective, Evidence Finish Line, Multi-Turn Path
• `fit-prompt-vs-goal` — Choose a Prompt for Single-Turn Work, a Goal for Outcome-Driven Continuation
• `fit-skip-for-vague-targets` — Skip a Goal When the Finish Line Is Vague

2. Outcome Definition (CRITICAL)

• `outcome-measurable-end-state` — State the Outcome as a Measurable End State, Not an Activity
• `outcome-quantify-thresholds` — Pin Thresholds with Numbers, Not Relative Comparatives
• `outcome-narrow-but-discoverable` — Make the Outcome Narrow Enough to Audit, Broad Enough to Allow Discovery
• `outcome-name-the-artifact` — For Generated Artifacts, Name the Artifact and Its Validity Conditions

3. Verification Surface (CRITICAL)

• `verify-name-the-surface` — Always Name the Verification Surface Inside the Goal
• `verify-include-constraints` — Include Constraints That Must Not Regress Alongside the Primary Metric
• `verify-multiple-checks-when-needed` — Use Multiple Verification Surfaces When a Single Check Is Insufficient
• `verify-surface-must-be-runnable` — The Verification Surface Must Be Something Codex Can Actually Run or Inspect

4. Boundaries & Iteration (HIGH)

• `bound-tools-and-files` — Bound the Files, Tools, and Repositories Codex May Use
• `bound-iteration-policy` — Define an Iteration Policy — How Codex Chooses the Next Experiment Between Turns
• `bound-blocked-stop-condition` — Define a Blocked Stop Condition — What to Report When No Defensible Path Remains
• `bound-respect-budget` — Treat the Budget Limit as Halt-and-Summarize, Not Extend

5. Lifecycle Commands (HIGH)

• `life-set-with-slash-goal` — Set a Goal with /goal <text> — Available from Codex 0.128.0
• `life-pause-during-detours` — Pause the Goal Before Unrelated Detours, Resume When Returning
• `life-clear-stale-goals` — Clear Stale Goals on Resumed Threads
• `life-inspect-with-slash-goal` — Use Bare /goal to Inspect Current Objective and State Before Continuation

6. Evidence-Based Completion (HIGH)

• `evidence-audit-before-completion` — Audit the Objective Against Concrete Evidence Before Marking a Goal Complete
• `evidence-budget-is-not-completion` — Reaching the Budget Limit Is Not the Same as Completing the Objective
• `evidence-honest-blockers` — Surface Blockers Explicitly — Never Substitute a Proxy for the Asked Claim

7. Crafting Strong Goals (MEDIUM)

• `craft-six-components` — Define Six Components in Every Strong Goal — Outcome, Verification, Constraints, Boundaries, Iteration Policy, Blocked Stop
• `craft-template-pattern` — Use the Canonical "verified by … while preserving … Use … Between iterations … If blocked …" Pattern
• `craft-let-codex-draft-it` — Ask Codex to Draft the Goal from a Plain-Language Description, Then Tighten
• `craft-strengthen-weak-goals` — Strengthen a Weak Goal by Naming the End State, Verification Surface, and Constraints

8. Research Goals & Anti-Patterns (MEDIUM)

• `research-define-evidence-standard-first` — For Research Goals, Define the Evidence Standard Before Investigation Begins
• `research-build-claim-inventory` — Decompose Research Goals into a Claim Inventory Mapped to Evidence Channels
• `research-preserve-epistemic-ledger` — Final Report Must Preserve Epistemic Levels Per Claim — Use a Structured Ledger Entry
• `research-anti-patterns` — Avoid the Three Common Goal Anti-Patterns — Keep-Going Wishes, Hidden Uncertainty, Overclaim on Proxy

How to Use

Read individual reference files for detailed explanations and worked examples comparing weak vs strong Goal text:

• Section definitions — Category structure and impact levels
• Rule template — Template for adding new rules

Each rule file contains:

• A 2-4 sentence explanation of WHY the rule matters
• An "Incorrect" example of a weak Goal or anti-pattern
• A "Correct" example showing how to strengthen it
• Reference back to the cookbook section it derives from

Reference Files

Codex (CLI) — Goals feature

Version 0.1.0 OpenAI May 2026

Note:

This document is mainly for agents and LLMs to follow when maintaining,

generating, or refactoring codebases. Humans may also find it useful,

but guidance here is optimized for automation and consistency by AI-assisted workflows.

---

Abstract

Patterns and anti-patterns for using OpenAI Codex Goals — the persistent objective feature introduced in Codex 0.128.0 that turns a thread from a sequence of isolated prompts into a stateful work loop with evidence-based completion. Contains 31 rules across 8 categories covering Goal fit decisions, outcome definition, verification surfaces, boundaries and iteration policy, lifecycle commands, evidence-based completion, crafting strong Goals, and research-Goal special cases. Each rule includes a 2-4 sentence rationale and a weak-vs-strong example pair derived from the official OpenAI cookbook article.

---

Table of Contents

1. Goal Fit Decisions — CRITICAL

• 1.1 Choose a Prompt for Single-Turn Work, a Goal for Outcome-Driven Continuation — CRITICAL (prevents miscategorizing work and choosing the wrong operating model)
• 1.2 Require Three Properties Before Setting a Goal — Durable Objective, Evidence Finish Line, Multi-Turn Path — CRITICAL (prevents Goals that either spin forever or finish in one turn anyway)
• 1.3 Skip a Goal When the Finish Line Is Vague — CRITICAL (prevents the most common Goal failure mode — open-ended objectives that never close)
• 1.4 Use a Goal When the Finish Line Is Clear but the Path Is Uncertain — CRITICAL (prevents misuse of persistence machinery on single-turn tasks)

2. Outcome Definition — CRITICAL

• 2.1 For Generated Artifacts, Name the Artifact and Its Validity Conditions — HIGH (enables artifact-level audit instead of completion based on plausibility)
• 2.2 Make the Outcome Narrow Enough to Audit, Broad Enough to Allow Discovery — HIGH (prevents both over-narrow Goals that miss the root cause and over-broad Goals with no audit surface)
• 2.3 Pin Thresholds with Numbers, Not Relative Comparatives — CRITICAL (eliminates the moving target where any positive delta passes for done)
• 2.4 State the Outcome as a Measurable End State, Not an Activity — CRITICAL (prevents drift by making every iteration check a boolean condition)

3. Verification Surface — CRITICAL

• 3.1 Always Name the Verification Surface Inside the Goal — CRITICAL (prevents completion claims grounded in model belief rather than concrete artifacts)
• 3.2 Include Constraints That Must Not Regress Alongside the Primary Metric — CRITICAL (prevents Pyrrhic completions where the headline metric improves but something important broke)
• 3.3 The Verification Surface Must Be Something Codex Can Actually Run or Inspect — CRITICAL (prevents Goals that look verifiable on paper but can't be checked in practice)
• 3.4 Use Multiple Verification Surfaces When a Single Check Is Insufficient — HIGH (prevents single-point-of-failure verification that misses important regressions)

4. Boundaries & Iteration — HIGH

• 4.1 Bound the Files, Tools, and Repositories Codex May Use — HIGH (prevents scope creep into unrelated code that risks side effects on critical-path systems)
• 4.2 Define a Blocked Stop Condition — What to Report When No Defensible Path Remains — HIGH (prevents Codex from declaring false completion or spinning when the real answer is "stuck")
• 4.3 Define an Iteration Policy — How Codex Chooses the Next Experiment Between Turns — HIGH (prevents thrashing and preserves learning across iterations via a recorded reasoning trail)
• 4.4 Treat the Budget Limit as Halt-and-Summarize, Not Extend — HIGH (prevents overspending by forcing halt-and-summarize at budget exhaustion)

5. Lifecycle Commands — HIGH

• 5.1 Clear Stale Goals on Resumed Threads — HIGH (prevents Codex from acting on an objective that no longer applies to the current work)
• 5.2 Pause the Goal Before Unrelated Detours, Resume When Returning — HIGH (prevents Codex from continuing toward the Goal while you're context-switching to unrelated work)
• 5.3 Set a Goal with `/goal <text>` — Available from Codex 0.128.0 — HIGH (prevents fallback to manual "keep going" prompts that miss the persistence and audit guarantees)
• 5.4 Use Bare `/goal` to Inspect Current Objective and State Before Continuation — HIGH (prevents surprise about what Codex thinks the active objective is)

6. Evidence-Based Completion — HIGH

• 6.1 Audit the Objective Against Concrete Evidence Before Marking a Goal Complete — HIGH (prevents completion claims based on model belief rather than verification surface output)
• 6.2 Reaching the Budget Limit Is Not the Same as Completing the Objective — HIGH (prevents overstating progress by collapsing budget-limited into complete)
• 6.3 Surface Blockers Explicitly — Never Substitute a Proxy for the Asked Claim — HIGH (prevents approximate evidence from being mislabeled as the asked claim)

7. Crafting Strong Goals — MEDIUM

• 7.1 Ask Codex to Draft the Goal from a Plain-Language Description, Then Tighten — MEDIUM (reduces authoring cost for strong Goals by splitting drafting from tightening)
• 7.2 Define Six Components in Every Strong Goal — Outcome, Verification, Constraints, Boundaries, Iteration Policy, Blocked Stop — MEDIUM (prevents missing components that predict Goal failure modes (Pyrrhic completion, scope creep, fake completion))
• 7.3 Strengthen a Weak Goal by Naming the End State, Verification Surface, and Constraints — MEDIUM (enables a repeatable weak-to-strong upgrade path for one-line aspirational Goals)
• 7.4 Use the Canonical "verified by … while preserving … Use … Between iterations … If blocked …" Pattern — MEDIUM (prevents partial Goals by surfacing empty clauses before activation)

8. Research Goals & Anti-Patterns — MEDIUM

• 8.1 Avoid the Three Common Goal Anti-Patterns — Keep-Going Wishes, Hidden Uncertainty, Overclaim on Proxy — MEDIUM (prevents three common Goal failure modes that produce untrustworthy completions)
• 8.2 Decompose Research Goals into a Claim Inventory Mapped to Evidence Channels — MEDIUM (prevents dropping or relabeling unverifiable claims by forcing per-claim status)
• 8.3 Final Report Must Preserve Epistemic Levels Per Claim — Use a Structured Ledger Entry — MEDIUM (prevents flattening confirmed/approximate/blocked into a single "done" claim)
• 8.4 For Research Goals, Define the Evidence Standard Before Investigation Begins — MEDIUM (prevents the final report from quietly drifting toward a single "done" claim across different epistemic levels)

---

References

1. https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex

---

Source Files

This document was compiled from individual reference files. For detailed editing or extension:

{{RULE_TITLE}}

{{EXPLANATION_1_TO_3_SENTENCES}}

Incorrect ({{WHAT_IS_WRONG}}):

```{{LANGUAGE}} {{BAD_CODE_EXAMPLE}}

{{OPTIONAL_BAD_EXPLANATION}}

**Correct ({{WHAT_IS_RIGHT}}):**

{{GOOD_CODE_EXAMPLE}}

{{OPTIONAL_GOOD_EXPLANATION}}

{{#IF ALTERNATIVE_APPROACHES}}
**Alternative ({{CONTEXT}}):**

{{ALTERNATIVE_CODE}}

{{ALTERNATIVE_EXPLANATION}}
{{/IF}}

{{#IF EXCEPTIONS}}
**When NOT to use this pattern:**

{{FOR_EACH EXCEPTION}}
- {{EXCEPTION}}
{{END_FOR_EACH}}
{{/IF}}

{{#IF WARNINGS}}
**Warning ({{WARNING_CONTEXT}}):**

{{WARNING_CONTENT}}
{{/IF}}

{{#IF REFERENCE}}
Reference: [{{REFERENCE_TITLE}}]({{REFERENCE_URL}})
{{/IF}}

Gotchas

No known gotchas yet. Append entries as they're discovered during use.

Format:

## {Short description of the failure}
What happens, and why.
Fix: what to do instead.
Added: YYYY-MM-DD

Sections

This file defines all sections, their ordering, impact levels, and descriptions. The section ID (in parentheses) is the filename prefix used to group rules.

---

1. Goal Fit Decisions (fit)

Impact: CRITICAL Description: Choosing whether a task needs a Goal at all — Goals are for outcomes that require iteration against evidence, not for one-shot edits or vague aspirations. A misfit Goal either spins without a stop condition or wastes the persistence machinery on work a single prompt would have closed.

2. Outcome Definition (outcome)

Impact: CRITICAL Description: Pinning the end state precisely enough to audit yet broadly enough to allow Codex to discover the path. Vague outcomes ("improve performance", "make this better") give Codex no completion condition; over-narrow outcomes ("fix this exact line") block discovery of the real root cause.

3. Verification Surface (verify)

Impact: CRITICAL Description: Naming the concrete evidence that proves the Goal is done — a test, benchmark, artifact, command output, or source material. Without a verification surface, Codex falls back to model belief, and "probably done" replaces "evidence says done".

4. Boundaries & Iteration (bound)

Impact: HIGH Description: Constraining what Codex may touch, how it should choose the next experiment between iterations, and what to report when no defensible path remains. Boundaries prevent scope creep; an iteration policy prevents wandering; a blocked stop condition prevents fake completion.

5. Lifecycle Commands (life)

Impact: HIGH Description: Managing the Goal's state through /goal, /goal pause, /goal resume, and /goal clear. Goals are thread-scoped persistent state — failing to pause during detours or clear on resumed threads causes Codex to continue against a stale objective.

6. Evidence-Based Completion (evidence)

Impact: HIGH Description: Completion is decided by evidence, not by the model's confidence. Budget limits halt work and require summary, not a "done" claim. Blockers must be surfaced explicitly — substituting proxies for the asked claim is how plausible artifacts become overclaimed conclusions.

7. Crafting Strong Goals (craft)

Impact: MEDIUM Description: Patterns for turning a weak Goal into a strong one — the six-component contract (outcome, verification, constraints, boundaries, iteration policy, blocked stop), the canonical template, and the two-step "draft with Codex, then tighten" workflow.

8. Research Goals & Anti-Patterns (research)

Impact: MEDIUM Description: Investigation Goals where exact proof may not be available — define the evidence standard before work begins, build a claim inventory, and preserve epistemic levels in the final report. Anti-patterns: using Goals as "keep going" without a stop condition, hiding uncertainty in the Goal text, or overclaiming on proxy evidence.

Define a Blocked Stop Condition — What to Report When No Defensible Path Remains

Sometimes Codex cannot complete a Goal — the data is unavailable, the benchmark is broken, the required API doesn't exist, the change would violate the constraints. The Goal must tell Codex what to do in that case. Without a blocked stop condition, Codex either declares completion against a proxy (hiding the failure) or loops trying weaker and weaker fixes. Spell out the stop contract: under what conditions to stop, what evidence to gather before stopping, and what the user needs to unblock progress. "Blocked" is a valid Goal terminal state — when it's the truthful one, surfacing it is the highest-value action Codex can take.

Incorrect (no blocked stop condition):

/goal Reduce p95 checkout latency below 120 ms on bench/checkout
while keeping the correctness suite green

# If the only path to <120 ms requires a database index Codex cannot
# create, Codex may either keep trying weaker fixes that can't reach
# the target or "improve" something and declare progress. The user
# never learns the actual blocker.

Correct (blocked stop condition stated):

/goal Reduce p95 checkout latency below 120 ms on bench/checkout
while keeping the correctness suite green. Use only services/checkout/**.

If blocked or no valid paths remain inside the boundary:
1. Stop substantive work.
2. Report:
   - Paths attempted (with iteration log entries).
   - Best result achieved (latency, error rate).
   - The blocker (what specifically prevents further progress).
   - The next input needed to unblock (a permission, a credential,
     a constraint relaxation, a boundary expansion, a missing tool).
3. Do not declare the Goal complete and do not continue iterating
   inside the boundary if you've exhausted the search space.

# Codex has a defined off-ramp. The user gets a structured blocker
# report instead of a fake "done" or an indefinite spin.

Reference: Using Goals in Codex — How to write a Goal

Define an Iteration Policy — How Codex Chooses the Next Experiment Between Turns

Between iterations, Codex must decide what to try next. Without instruction, this defaults to "try the next plausible thing", which is fast but throws away the learning from each attempt. An iteration policy tells Codex how to choose the next experiment: record what changed, what the evidence showed, and what the next best step is given the evidence. This produces a reasoning trail that compounds — by iteration 5, Codex has a written history of what was tried, what worked, what didn't, and why. The policy also slows Codex down enough to avoid thrashing on the same hot path with cosmetically different fixes.

Incorrect (no iteration policy — opaque trial and error):

/goal Reduce p95 checkout latency below 120 ms on bench/checkout
while keeping the correctness suite green. Use only services/checkout/**.

# Codex tries fix A → benchmark → tries fix B → benchmark → tries fix C.
# No record of what each attempt was supposed to test. If it succeeds,
# we don't know which fix mattered. If it fails, we may repeat fixes.

Correct (named iteration policy):

/goal Reduce p95 checkout latency below 120 ms on bench/checkout
while keeping the correctness suite green. Use only services/checkout/**.

Between iterations:
1. Record what changed (one-line diff summary).
2. Record what the benchmark showed (p95, p99, error rate).
3. Record the hypothesis you're testing and whether it was confirmed.
4. Choose the next experiment based on the highest-impact bottleneck
   in the most recent flamegraph, not on aesthetic improvements.
5. Maintain this log in bench/checkout/iteration-log.md, appending
   one entry per iteration.

# Each iteration leaves a written trace. The log is itself an artifact
# the user can review even before the Goal completes. Codex picks the
# next experiment from evidence, not intuition.

Reference: Using Goals in Codex — How to write a Goal

Treat the Budget Limit as Halt-and-Summarize, Not Extend

Goals have a budget — a cost ceiling beyond which Codex must stop substantive work. When the budget is reached, the correct behavior is to stop, summarize progress and blockers, and identify the next useful step. The wrong behavior is to declare completion based on what's been done so far, or to push past the budget on the grounds that "one more iteration would do it". Reaching the budget is the system's signal that the work is going to cost more than the user authorized. Surface that to the user; let them decide whether to extend, pause, or close. Treating budget exhaustion as completion is a quiet way to overspend the contract.

Incorrect (budget exhaustion treated as completion):

[Goal active]
[10 iterations completed; budget exhausted]
Codex: "I've made significant progress on the latency target.
Latency improved from 180 ms to 145 ms. Marking the Goal complete."

# Latency target was below 120 ms. 145 ms is not complete.
# Codex hit the budget and rewrote the contract to fit what was done.
# The user now believes the Goal succeeded when it didn't.

Correct (budget exhaustion triggers structured summary):

[Goal active]
[10 iterations completed; budget exhausted]
Codex: "Budget reached. Goal not complete.

Progress:
- Latency reduced from 180 ms → 145 ms (target: < 120 ms).
- Correctness suite still green.
- Iteration log: bench/checkout/iteration-log.md.

Blockers identified for further progress:
- The remaining 25 ms is concentrated in two database queries that
  need an index change in shared/db (outside the boundary).

Next useful step: relax the boundary to allow a migration in
shared/db, or extend the budget for another 5 iterations within the
current boundary (lower expected impact).

Recommend: pause for user decision."

# Honest summary of progress and remaining gap. Concrete next options
# for the user. Goal is not marked complete and is not silently extended.

Reference: Using Goals in Codex — How Goals are designed in Codex

Bound the Files, Tools, and Repositories Codex May Use

A Goal without boundaries lets Codex touch anything it judges relevant — including systems that are not part of the work. State the boundaries explicitly: which directories, which tools, which external services. The narrower the blast radius, the less review surface the user inherits when the Goal completes. Boundaries also help Codex avoid distractions — a perf Goal that's allowed to "investigate everything" tends to drift into refactors that pad the diff without moving the metric. Keep Codex inside the boundary by stating it inside the Goal text; do not rely on it being inferred.

Incorrect (no boundaries — anything is in scope):

/goal Reduce p95 checkout latency below 120 ms while keeping the
correctness suite green

# Codex may edit shared library code that other services depend on,
# add a caching layer in an unrelated module, or "while I'm here"
# refactor utility code. The diff balloons; review takes hours.

Correct (explicit file/tool boundaries):

/goal Reduce p95 checkout latency below 120 ms on bench/checkout
while keeping the correctness suite (tests/integration/checkout/**)
green. Use only:
- files under services/checkout/**
- the benchmark fixtures under bench/checkout/fixtures/**
- the tests under tests/integration/checkout/**
Do not edit shared libraries, public API contracts, or anything
outside these paths. If a change outside this boundary is required,
stop and report it as a blocker.

# Blast radius confined to one service. Anything outside requires
# explicit user input. Diff is reviewable; Codex cannot silently
# expand scope.

Reference: Using Goals in Codex — How to write a Goal

Ask Codex to Draft the Goal from a Plain-Language Description, Then Tighten

When the task is clear but the Goal text is not, ask Codex to write the Goal for you. Step one: describe what you want in plain language and ask Codex to turn it into a draft /goal. Step two: review the draft and tighten the success condition, verification surface, constraints, and blocked stop condition before activating. Codex is good at producing a draft that includes the six components in the canonical pattern — what it can't do is read your mind about which surfaces matter most, which constraints are non-negotiable, or what the real unblocking inputs are. The draft saves time; the tightening saves correctness. Don't activate Codex's first draft as-is — that's a category of Goal that looks complete but isn't.

Incorrect (skip the draft, write a thin Goal by hand under time pressure):

User: /goal Fix the flaky checkout test

# No verification surface specified, no constraint on side effects,
# no blocked stop. Thin Goals from impatient hand-writing are how
# Goals fail.

Correct (two-step: ask Codex to draft, then tighten):

User: "Help me turn this into a strong /goal: I want Codex to keep
working on the flaky checkout test until we either fix it with
evidence or can clearly explain what's blocking progress."

Codex (draft): "/goal Reproduce and fix the flakiness in
tests/checkout/test_payment_flow, verified by 100 consecutive passing
runs of that test on a clean checkout, while preserving all other
tests in tests/checkout/** passing and the public CheckoutController
API unchanged. Use only files under services/checkout/** and
tests/checkout/**. Between iterations, record the failure mode
observed, the hypothesized cause, the fix attempted, and the result.
If the flake cannot be reproduced or the cause is outside the
boundary, report the attempted paths, the evidence gathered, the
blocker, and the next input needed."

User (after review): "Tighten — change '100 consecutive runs' to
'500 runs with no more than 1 failure', and add that the fix must
not extend total suite runtime by more than 10%."

User: /goal [tightened version]

# Codex's draft gives a complete-looking Goal. The user's review
# catches what Codex couldn't infer (real flakiness threshold,
# performance constraint) before activation.

Reference: Using Goals in Codex — How to write a Goal

Define Six Components in Every Strong Goal — Outcome, Verification, Constraints, Boundaries, Iteration Policy, Blocked Stop

The strongest Goals typically define six things explicitly: (1) outcome — what should be true when the work is done; (2) verification surface — the test, benchmark, report, artifact, command output, or source material that proves it; (3) constraints — what must not regress while Codex works; (4) boundaries — which files, tools, data, repositories, or resources Codex may use; (5) iteration policy — how Codex should decide what to try next after each attempt; (6) blocked stop condition — when Codex should stop and report that no defensible path remains. Use the checklist when writing or reviewing a Goal. Missing components don't break the Goal immediately, but they predict where it will go wrong: missing constraints predict Pyrrhic completions; missing boundaries predict scope creep; missing blocked stops predict spinning or fake completion.

Incorrect (thin Goal — only outcome and one constraint):

/goal Reduce p95 checkout latency below 120 ms without regressing
correctness tests

# Missing: verification surface (which benchmark? which suite?),
# boundaries (where can Codex edit?), iteration policy (how to choose
# the next experiment?), blocked stop (what to do when stuck?).
# Workable but will produce avoidable surprises.

Correct (all six components stated):

/goal Reduce p95 checkout latency below 120 ms,
verified by `npm run bench:checkout` reporting p95 < 120 ms across
50 runs,
while keeping the correctness suite (tests/integration/checkout/**)
green and the public CheckoutController API unchanged.
Use only files under services/checkout/**, bench/checkout/**, and
tests/integration/checkout/**.
Between iterations, record what changed, what the benchmark showed,
and the next best experiment to try in bench/checkout/iteration-log.md.
If the benchmark cannot run or no valid paths remain inside the
boundary, stop with attempted paths, evidence gathered, the blocker,
and the next input needed.

# (1) Outcome: p95 < 120 ms.
# (2) Verification: bench:checkout, 50 runs.
# (3) Constraints: integration suite green, public API unchanged.
# (4) Boundaries: three named paths only.
# (5) Iteration policy: record-changed/showed/next, log location.
# (6) Blocked stop: defined trigger and report contents.

Reference: Using Goals in Codex — How to write a Goal

Strengthen a Weak Goal by Naming the End State, Verification Surface, and Constraints

Most weak Goals share the same shape — they name a direction without an end state, or an outcome without evidence, or a metric without a constraint. The fastest upgrade path is the same in every case: explicitly name (a) the end state as a measurable condition, (b) the verification surface that proves it, and (c) the constraints that must not regress. Just doing those three turns most weak Goals into workable ones. The remaining three components (boundaries, iteration policy, blocked stop) take Goals from workable to strong, but the first three are the difference between a Goal that can complete and a Goal that can't.

Incorrect (weak — direction only):

/goal Improve performance

# Direction without end state. No verification. No constraints.
# The fastest weak Goal to spot — and to fix.

Correct (strengthened — end state + verification + constraint):

/goal Reduce p95 latency below 120 ms on the checkout benchmark while
keeping the correctness test suite green

# End state: p95 < 120 ms.
# Verification: the checkout benchmark.
# Constraint: correctness suite still green.
# Workable. From here, adding boundaries, iteration policy, and a
# blocked stop makes it strong. But this version already terminates
# correctly.

Alternative (same pattern applied to a docs Goal):

# Weak:
/goal Write docs for this feature

# Strengthened:
/goal Produce a docs page for Goals that explains the lifecycle,
command surface, and two examples. Verify that the page builds
locally and that all referenced commands match the current CLI
behavior.

# Same upgrade: end state (docs page exists with named sections),
# verification (builds locally; commands match CLI), constraint
# (commands referenced must be current).

Reference: Using Goals in Codex — Turning a weak Goal into a strong one

Use the Canonical "verified by … while preserving … Use … Between iterations … If blocked …" Pattern

The cookbook gives a canonical scaffold that maps to the six components: /goal <desired end state> verified by <specific evidence> while preserving <constraints>. Use <allowed inputs, tools, or boundaries>. Between iterations, <how Codex should choose the next best action>. If blocked or no valid paths remain, <what Codex should report and what would unlock progress>. Start drafts from this pattern. If a clause feels empty, stop and define it before activating — that's exactly the kind of input you want to surface before Codex starts iterating, not after. The scaffold is not the only form a Goal can take, but it's a strong default when you're not sure what to include.

Incorrect (free-form Goal that omits half the contract):

/goal I want the checkout flow to be faster and still work, focus on
the new flow that we shipped last week

# Direction (faster) but no threshold. Constraint ("still work") but
# no surface to verify it. Boundary hint ("new flow") but not pinned
# to paths. No iteration policy, no blocked stop. Six components, two
# half-defined.

Correct (canonical scaffold filled in):

/goal Cut p95 latency of POST /checkout/submit below 250 ms,
verified by `npm run bench:checkout-submit` reporting p95 < 250 ms
across 100 runs,
while preserving the integration suite (tests/checkout/**) green and
the request/response schema unchanged.
Use only files under services/checkout-submit/** and the benchmark
fixtures under bench/checkout-submit/**.
Between iterations, record one-line diff, benchmark p95/p99/error rate,
and the hypothesis being tested in bench/checkout-submit/iteration-log.md.
If the benchmark cannot run or no valid paths remain, stop and report
the attempted paths, evidence gathered, the blocker, and the next
input needed to unblock.

# Pattern: end state → verification → constraints → boundaries →
# iteration policy → blocked stop. Every clause filled. Codex has a
# complete operating contract from turn one.

Reference: Using Goals in Codex — How to write a Goal

Audit the Objective Against Concrete Evidence Before Marking a Goal Complete

A Goal should only be marked complete after the objective has been checked against the relevant files, tests, logs, benchmark output, generated artifacts, or research evidence. Codex's belief that completion is likely is not evidence; only the verification surfaces named in the Goal are. This is the design center of Goals — the architecture lets Codex keep moving across turns, but the evidence decides when it's done. The audit is not optional and not implicit. Before declaring complete, Codex must run the named checks (benchmark, suite, build, query), confirm the result against the Goal's threshold, and confirm constraints are not violated. If any named check is skipped or any constraint is unverified, the Goal is not complete.

Incorrect (declaring complete on model belief):

[Iteration 4 of latency Goal]
Codex: "I've applied the database connection pooling fix from
iteration 3 and removed the redundant JSON serialization from
iteration 4. Based on the changes, p95 latency should now be well
below 120 ms. Marking the Goal complete."

# "Based on the changes... should now be" is belief, not evidence.
# The benchmark was not run. The correctness suite was not run.
# The "complete" claim is unverified.

Correct (run the verification surfaces, then complete):

[Iteration 4 of latency Goal]
Codex: "Running named verification surfaces before marking complete.
- bench/checkout (50 runs): p95 = 108 ms ✓ (target < 120 ms)
- tests/integration/checkout/** : 47/47 pass ✓
- error rate: 0.04% ✓ (constraint < 0.1%)
- public CheckoutController API: unchanged ✓ (constraint)
All verification surfaces satisfied. Marking Goal complete."

# Every named surface was run. Every threshold and constraint was
# verified. The complete claim is backed by evidence.

Reference: Using Goals in Codex — What changes when a Goal is active

Reaching the Budget Limit Is Not the Same as Completing the Objective

A Goal has two distinct terminal states the user must keep separate: complete (the evidence shows the outcome is true) and budget-limited (Codex ran out of authorized iterations or cost ceiling without reaching completion). These look superficially similar — both end with Codex stopping — but their meanings are opposite. Completion means the contract was satisfied. Budget exhaustion means the contract was not satisfied within the authorized cost. Treating budget exhaustion as completion silently overstates progress. The Goals architecture treats them as separate states for exactly this reason; honor the distinction in the user-facing summary. When budget is reached, the right action is to summarize progress, identify what would unblock further progress, and let the user decide whether to extend, pause, or close.

Incorrect (collapsing budget-limited into complete):

[Budget reached at iteration 12; latency Goal not satisfied]
Codex: "Goal complete. Latency reduced from 180 ms to 145 ms."

# Target was < 120 ms. 145 ms is not complete. The "complete" label
# misrepresents the state to anyone reading the log later.

Correct (budget-limited stated as its own terminal state):

[Budget reached at iteration 12; latency Goal not satisfied]
Codex: "Goal state: budget-limited (not complete).

Best result: p95 = 145 ms (target < 120 ms).
Constraints honored: correctness suite green, API unchanged.

To reach the target, the next iterations would need:
- Index change in shared/db (currently outside boundary), or
- Caching layer in services/checkout/cache (estimated 2 more iterations)

Recommend: extend budget by 5 iterations with caching path, or expand
boundary to allow the index change, or close the Goal at this
partial improvement."

# "Budget-limited (not complete)" is unambiguous. The user can choose
# the next step from real options instead of inheriting a "done" label
# that hides the gap.

Reference: Using Goals in Codex — How Goals are designed in Codex

Surface Blockers Explicitly — Never Substitute a Proxy for the Asked Claim

When the asked verification cannot be performed — because the data isn't available, the surface can't run, or the path requires something Codex doesn't have — the right action is to surface the blocker, not to silently substitute a proxy. A proxy can support a claim, raise confidence, or partially validate the result, but it must be labeled as a proxy, not reported as the asked claim. This is what distinguishes a Goal report you can trust from one that looks plausible but is wrong in places that matter. The same principle applies inside long iterations: when one check fails or can't run, name it as a gap, not as a substitution. Honest labels are the difference between an audit and a marketing claim.

Incorrect (proxy substituted for the asked claim):

[Asked: "verified by reproducing the published Heston reference price"]

Codex: "Heston reference price reproduced. Goal complete."

[What actually happened: the original training paths, seeds, and
checkpoints were unavailable. Codex trained a new policy with new
seeds and reported the new policy's price as the reproduction.]

# A close approximation was reported as exact reproduction.
# The asked claim ("reproduce the published price") was not verified —
# a new training run with different seeds was, and it was relabeled
# as the asked claim. The report cannot be trusted.

Correct (proxy clearly labeled; original claim marked blocked):

[Asked: "verified by reproducing the published Heston reference price"]

Codex: "Reproduction status:
- Original published price: NOT exactly reproduced. The paper does not
  provide the random seeds, training paths, or saved checkpoints needed
  for exact replay. Status: blocked.
- Approximate reproduction (new training run, new seeds): produced a
  Heston reference price within 0.6% of the published value across
  three independent seeds.

Recommendation: treat this as a close approximate reproduction
supporting the claim, not an exact replay. Goal state: partial
completion with one blocked dimension."

# The asked claim is marked blocked with the reason.
# The supporting evidence is clearly labeled as approximate.
# The reader can judge what the result means.

Reference: Using Goals in Codex — Using Goals for complex research

Choose a Prompt for Single-Turn Work, a Goal for Outcome-Driven Continuation

The two operating models are not interchangeable. A prompt is "ask → work → result → wait" — Codex executes the immediate instruction, reports back, and stops. A Goal is "work → check → continue or complete" — Codex evaluates evidence after each turn and continues if the objective is still unmet and the Goal is within budget. The cost of confusing the two is real: a prompt forced into a Goal-shaped task makes the user retype "keep going" every turn; a Goal forced onto a prompt-shaped task attaches state Codex must maintain for work that closes in one turn. Diagnose the shape before choosing.

Incorrect (prompt repeated where a Goal belongs):

User: Profile the request handler and find the slowest path
Codex: [profiles, reports top 3 hot functions]
User: Now fix the top one
Codex: [fixes function A]
User: Now rerun the benchmark
Codex: [reruns, latency still above target]
User: Try fixing the next one
Codex: [fixes function B]
User: Rerun and check

# Every "next" turn the user restates the target. The objective lives
# in the user's head, not the thread. Codex cannot evaluate completion
# between turns because there is no persisted finish line.

Correct (Goal for the iterative outcome, prompts for one-shot probes):

/goal Reduce p95 request latency below 80 ms on the staging benchmark
while keeping the integration tests green

# Mid-Goal one-shot probe — does not need its own Goal:
What does the flamegraph from the last benchmark run show as the top
allocator?

# The Goal owns the outcome. One-shot prompts during the Goal are
# fine — they answer specific questions without redefining the target.
# Codex returns to the Goal after answering.

Reference: Using Goals in Codex — Goals vs prompts

Skip a Goal When the Finish Line Is Vague

"Make this better", "refactor this", and "improve the codebase" are not Goals — they are wishes. A Goal must give Codex a way to know when it is done. If you cannot complete the sentence "the work is done when ___ is true", you do not have a Goal yet. The fix is not to set the Goal and hope Codex narrows it; the fix is to define the finish line before activating. Either name the metric ("test suite passes", "p95 < X"), the artifact ("a docs page that explains Y and builds locally"), or the constraint set ("public API behavior unchanged"). If you cannot name any of these, the task is not Goal-shaped — use a prompt to scope the work first.

Incorrect (vague target, no finish line):

/goal Refactor this code

# Finish line: undefined.
# Codex either spins (each turn finds more to "refactor") or declares
# completion based on aesthetic judgment that may not match the user's.
# The Goal looks active but is structurally identical to "keep working".

Correct (finish line pinned to verifiable state):

/goal Refactor the OrderProcessor module so that no method exceeds 30
lines and the existing test suite passes unchanged. Public API of
OrderProcessor must remain the same — adding tests is allowed,
changing call sites is not.

# End state: every method ≤ 30 lines.
# Verification: existing tests pass; public API unchanged.
# Codex can audit each turn against measurable conditions.

When NOT to use this pattern:

• Exploratory or open-ended research where the user genuinely wants the model to broaden the search — those are prompts, not Goals.

Reference: Using Goals in Codex — How to write a Goal

Require Three Properties Before Setting a Goal — Durable Objective, Evidence Finish Line, Multi-Turn Path

Goals are strongest when the task has all three properties: a durable objective (something that persists meaningfully across turns), an evidence-based finish line (a concrete artifact, test, benchmark, or report that proves completion), and a path that may require several turns of investigation. Missing any one collapses the Goal — without a durable objective it's a prompt; without an evidence finish line Codex can't tell when to stop; without a multi-turn path the persistence is overhead. Check all three before typing /goal. If even one is missing, either fix the input (define the evidence) or drop back to a prompt.

Incorrect (objective without evidence finish line):

/goal Improve the developer onboarding experience

# Durable objective? Yes — "improve" persists across turns.
# Evidence finish line? No — how does Codex prove "improved"?
# Multi-turn path? Possibly, but the missing evidence finish line
# is already enough to disqualify the Goal.
# Result: Codex cannot decide when it's done. Loops or declares
# false completion based on model belief.

Correct (all three present):

/goal Cut time-to-first-commit for a new engineer below 30 minutes,
verified by running the onboarding script end-to-end on a clean
machine and recording timestamps for each step

# Durable objective: cut TTFC below 30 min.
# Evidence finish line: end-to-end script run with recorded timestamps.
# Multi-turn path: identify slow steps → fix → re-run → measure.
# All three present — Goal is well-formed.

When NOT to use this pattern:

• A vague aspiration with no defined metric ("make onboarding nicer") even when iteration would happen — fix the input first.
• A clearly bounded single edit ("change config X from A to B") — the multi-turn path is missing; a prompt is faster.

Reference: Using Goals in Codex — When not to use Goals

Use a Goal When the Finish Line Is Clear but the Path Is Uncertain

A Goal is a persistent objective with a completion contract. It is the right tool only when the work has both a verifiable end state and a path that may require several turns of investigation — performance tuning, flaky-test investigation, dependency migration, multi-step refactor, benchmark-driven tuning, or research producing a final artifact. For a one-line edit, a code explanation, or a question with one answer, a normal prompt closes faster and avoids attaching state Codex must maintain. Misapplying Goals doesn't just waste machinery — it trains the user to ignore the lifecycle controls that make Goals safe.

Incorrect (Goal for a one-shot edit):

/goal Rename the variable userId to accountId in src/auth/session.ts

# This is a single deterministic edit. There is no iteration, no
# evidence to gather, no decision the next turn would make differently.
# A plain prompt completes it in one turn without persistent state.

Correct (Goal for an iterative outcome):

/goal Reduce p95 checkout latency below 120 ms on the checkout benchmark
while keeping the correctness suite green

# Iterative: inspect hot path → change → rerun benchmark → check tests
# → continue if not below threshold. Persistent objective survives
# intermediate results without restating the target each turn.

When NOT to use this pattern:

• One-line edits, simple explanations, short code reviews, or questions where you want one answer and then a stop.
• Tasks where the finish line is vague ("make this better", "refactor this") with no defined end state, tests, or constraints.
• Tasks where you would not be willing to let Codex spend multiple turns iterating.

Reference: Using Goals in Codex — Quickstart

Clear Stale Goals on Resumed Threads

When you resume a Codex thread that had an active Goal, the Goal comes back with it. That's usually what you want — but not always. If the work has moved on, the original Goal may no longer apply, or its boundary, constraints, or verification surface may now be wrong. Continuing against a stale Goal produces work that looks plausible but is aimed at the wrong target. Make it a habit on resumed threads to run /goal first to inspect what's still active, and to clear it with /goal clear if it no longer applies. Clearing is not destructive — the thread keeps its history; only the persistent objective is removed.

Incorrect (continuing a stale Goal on a resumed thread):

[Resume thread from yesterday]
[Goal still active: Reduce p95 checkout latency below 120 ms]

User: Now I want to add a new feature flag for the recommendations panel
Codex: [reads the message, but the Goal continuation kicks in after
the new feature is added — Codex tries to also optimize the latency
of the new code path because the Goal is still active]

# The Goal is irrelevant to the new work but still gates continuation.
# Codex inserts performance work where the user wanted a simple flag.

Correct (inspect, then clear, then start new work):

[Resume thread from yesterday]

User: /goal
Codex: [displays the active Goal — exact format varies by version,
but typically includes the Goal text and current state such as
active / paused / complete / budget-limited]

User: /goal clear
[Goal cleared]

User: Now I want to add a new feature flag for the recommendations panel
Codex: [handles the new request without persistence machinery from
the previous Goal]

# The old Goal is inspected, confirmed irrelevant, and cleared.
# The new work runs cleanly without inherited objectives.

Reference: Using Goals in Codex — Quickstart and lifecycle

Use Bare /goal to Inspect Current Objective and State Before Continuation

Typing /goal with no arguments displays the current Goal — its text, its state (active, paused, complete, budget-limited), and its progress. This is the first thing to do when (a) you resume a thread, (b) Codex's behavior between turns surprises you, or (c) you're about to set a new Goal and want to confirm there isn't one already. The Goal is persisted state — you can't assume it matches your mental model unless you've checked. Inspecting is free; surprises later are not. The same command is also useful as a checkpoint mid-Goal to confirm what Codex is iterating against.

Incorrect (assuming what the active Goal is without checking):

[Resume thread from last week]

User: Keep working on the latency Goal
Codex: [Goal in the thread is actually "Cut bundle size below 500 KB",
not latency — Codex starts conflating the two objectives]

# The user remembered the wrong Goal. Codex tried to continue against
# the one that's actually stored. Behavior diverges from intent.

Correct (inspect first):

[Resume thread from last week]

User: /goal
Codex: [shows the currently stored Goal text and its state — the
exact display format varies by Codex version, but the surfaced
information should include the Goal text, its lifecycle state, and
some form of progress indicator]

User: Right — that's still the priority. Continue from the last
iteration.

# Inspection corrects the user's memory before action. Codex continues
# against the actual Goal, not a confabulated one.

Reference: Using Goals in Codex — Quickstart

Pause the Goal Before Unrelated Detours, Resume When Returning

When you have an active Goal and need to do something unrelated in the same thread — answer a quick question, run a probe, look at unrelated code — pause the Goal with /goal pause first. Otherwise, after each unrelated turn completes, Codex may attempt to continue the Goal, applying the persistence machinery to a thread that's no longer focused on the objective. Pausing decouples the side work from the Goal's continuation logic. Resume with /goal resume when you're returning to the main objective. The Goal's progress, budget, and iteration log are preserved across the pause — pause is cheap and safe.

Incorrect (unrelated probe during an active Goal, no pause):

[Goal active: Reduce p95 latency below 120 ms]

User: Before the next iteration — what's the schema of the
recommendations table?
Codex: [answers the question]
[Goal still active; Codex now attempts to continue iterating on
latency, possibly mixing the side-investigation context into the
next experiment]

# Side investigation is now entangled with the latency work. Codex
# may try to optimize the recommendations table because it just looked
# at it, even though the table is outside the Goal's boundary.

Correct (pause for the detour, resume after):

[Goal active: Reduce p95 latency below 120 ms]

User: /goal pause
[Goal paused]

User: What's the schema of the recommendations table?
Codex: [answers cleanly; no continuation pressure]

User: /goal resume
[Goal resumed — continues iterating on latency from the last state]

# The pause draws a hard line between Goal work and side work.
# Codex doesn't carry the side context into the next Goal iteration.

Reference: Using Goals in Codex — Quickstart

Set a Goal with /goal <text> — Available from Codex 0.128.0

Goals are activated by typing /goal followed by the objective text. The Goal then persists across turns in the thread, with continuation, evidence checks, and budget accounting attached. Goals require Codex 0.128.0 or later. Before relying on them in a workflow, confirm the installed version with codex --version. Older versions silently ignore the command and fall back to treating it as plain text — which means you think you have a persistent objective when you actually have a prompt. Upgrade with npm install -g @openai/codex@latest or brew upgrade --cask codex.

Also check feature gating. Goals shipped as an experimental feature; depending on your version, /goal may need to be explicitly enabled (in config.toml, via an /experimental toggle, or via a CLI flag — the exact mechanism varies by release). The failure mode is the same as version mismatch: the command falls through as plain text and you have a prompt instead of a Goal. If codex --version confirms 0.128.0+ but /goal doesn't behave persistently, check codex --help and the current Codex docs for the feature-enablement step before assuming the Goal is active.

Incorrect (using a Codex version that doesn't support Goals):

$ codex --version
codex 0.124.3

$ codex
> /goal Reduce p95 latency below 120 ms
[Codex treats this as a normal prompt — no Goal is set]
[Next turn: no continuation, no evidence audit, no budget]

# The "/goal" text was treated as a regular message. No persistent
# objective exists. The user believes the Goal is active when it isn't.

Correct (verify version, then set Goal):

$ codex --version
codex 0.128.0

$ codex
> /goal Reduce p95 checkout latency below 120 ms on bench/checkout
while keeping the correctness suite green
[Goal active]

# Version supports Goals. The /goal command sets a persistent objective.
# Subsequent turns benefit from continuation, evidence audit, and
# budget accounting.

Reference: Using Goals in Codex — Quickstart

State the Outcome as a Measurable End State, Not an Activity

A Goal's outcome should describe what is true when the work is done, not what Codex is doing along the way. "Optimize the renderer" describes activity — there is no point at which optimization is provably done. "Reduce render time of the dashboard below 16 ms per frame on the perf harness" describes an end state Codex can check after each iteration. Activity-shaped outcomes drift; end-state outcomes terminate. The test is simple: can you write a single boolean expression that evaluates true the moment the work is done? If yes, the outcome is end-state-shaped. If no, rewrite it.

Incorrect (activity-shaped):

/goal Optimize the dashboard renderer for better performance

# "Optimize" and "better" are verbs and comparatives. No terminal
# condition. After any improvement, "better" still admits further
# improvement — the Goal never satisfies.

Correct (end-state-shaped):

/goal Reduce dashboard render time to below 16 ms per frame on the
existing perf harness, measured across the same five fixtures the
harness already uses

# Boolean condition: render_time_ms < 16 across all five fixtures.
# Codex runs the harness after each change and checks the condition.
# The Goal terminates the moment the condition holds.

Reference: Using Goals in Codex — How to write a Goal

For Generated Artifacts, Name the Artifact and Its Validity Conditions

When the outcome is a generated artifact — docs, a config file, a migration, a report — the Goal must name both the artifact and the conditions that make it valid. "Write docs for this feature" gives Codex nothing to audit. A stronger formulation names what the page must contain, where it lives, and what "builds and works" means. Codex can then inspect the produced artifact against those conditions instead of declaring completion on plausibility. The validity conditions are the audit surface for artifact Goals — they are not optional decoration.

Incorrect (no artifact specification):

/goal Write docs for the new Goals feature

# What page? Where? In what format? What must it cover?
# Codex produces something plausible. Whether it's complete or correct
# is a matter of opinion, not audit.

Correct (artifact + validity conditions):

/goal Produce a docs page for Goals at docs/codex/goals.md that
explains the lifecycle (set, pause, resume, clear, complete), the
command surface, and two end-to-end examples (one performance, one
research). Verify that the page builds locally with the existing
docs build script and that every referenced command matches the
current CLI behavior in `codex --help`.

# Artifact: docs/codex/goals.md
# Required sections: lifecycle, command surface, two examples
# Validity checks: builds locally; commands match `codex --help`
# Codex can inspect the produced page against each condition.

Reference: Using Goals in Codex — Turning a weak Goal into a strong one

Make the Outcome Narrow Enough to Audit, Broad Enough to Allow Discovery

Goal scope sits on a spectrum. Too narrow ("fix line 42 of session.ts") blocks discovery — if the real bug is in an upstream dependency, the Goal is unsolvable as stated. Too broad ("improve the whole system") has no audit surface — Codex cannot prove completion. The sweet spot is an outcome that names the user-observable behavior or measurable property while leaving the implementation path open. "Make the checkout test suite pass on the current branch without changing public API behavior" is a strong example: it names what must be true (suite passes, API unchanged), but does not prescribe where the bug is or how to fix it. Codex can investigate, find the actual cause, and verify against the audit surface.

Incorrect (over-narrow — prescribes the fix location):

/goal Fix the bug in CheckoutController.processPayment that's making
the integration test fail

# If the failure is caused by a stale fixture, a race in the queue
# worker, or an upstream API change, this Goal is unsolvable as stated.
# Codex is constrained to a location that may not contain the bug.

Correct (names the behavior, leaves the path open):

/goal Make the checkout integration test suite pass on the current
branch without changing the public API behavior of CheckoutController

# Audit surface: the test suite.
# Constraint: public API of CheckoutController unchanged.
# Path: open — Codex can investigate fixtures, queue, upstream, or the
# controller itself, and verify any fix against the suite.

Reference: Using Goals in Codex — How to write a Goal

Pin Thresholds with Numbers, Not Relative Comparatives

Comparatives ("faster", "smaller", "fewer") have no termination point — any positive delta technically satisfies them, but no specific delta is enough. Pin the threshold with a number Codex can check absolutely. "Reduce p95 latency" is a direction; "reduce p95 latency below 120 ms" is a target. The difference is whether Codex can declare completion. With a numeric threshold, a benchmark run answers yes or no. Without one, the Goal stays open even after large wins because "could be faster still" is always true. Numbers are how outcomes become auditable.

Incorrect (comparative without anchor):

/goal Make checkout faster

# 180 ms → 175 ms satisfies "faster". 180 ms → 50 ms also satisfies it.
# Codex has no way to choose between "we improved enough" and "keep going".
# Either it stops too early or it never stops.

Correct (numeric threshold):

/goal Reduce p95 checkout latency below 120 ms on the checkout
benchmark while keeping the correctness suite green

# Threshold: p95 < 120 ms.
# 180 → 135 ms: not done, keep iterating.
# 180 → 118 ms: done (if correctness suite is still green).
# No ambiguity.

When NOT to use this pattern:

• Outcomes that are inherently boolean or categorical (e.g., "all tests pass", "compilation succeeds") — the threshold is implicit.

Reference: Using Goals in Codex — Turning a weak Goal into a strong one

Avoid the Three Common Goal Anti-Patterns — Keep-Going Wishes, Hidden Uncertainty, Overclaim on Proxy

Three patterns repeatedly produce Goals that look complete but are wrong in ways that matter. (1) Keep-going wishes: "continue until X is done" where X is undefined — there's no verifiable terminal condition, so Codex either spins or fakes completion. (2) Hidden uncertainty: a Goal text that doesn't acknowledge unavailable data or flaky surfaces, so Codex silently substitutes proxies and the user never learns the gaps. (3) Overclaim on proxy: an approximate or trained replacement is reported as the exact asked claim. Each of these is preventable by upgrading the Goal text up front. The pattern is consistent: when uncertainty exists, name it inside the Goal; when proxies are acceptable, define how they should be labeled; when "continue until X" is the goal, ensure X is verifiable.

Incorrect (all three anti-patterns at once):

/goal Reproduce the paper's results and keep going until you've
confirmed everything works

# (1) "Keep going until everything works" — no verifiable terminal.
# (2) Doesn't acknowledge that the paper may not provide all artifacts.
# (3) Doesn't define how proxies should be labeled — opens the door
#     to retraining with new seeds being reported as "confirmed".

Correct (anti-patterns addressed inline):

/goal Audit the reproducibility of Buehler et al., "Deep Hedging"
against the available materials.

- Terminal condition: every headline claim has a labeled status entry
  (confirmed / approximate reconstruction / proxy support / blocked).
  The Goal is complete when the ledger is exhaustive, not when every
  claim is confirmed.
- Acknowledged uncertainty: the paper does not provide random seeds,
  training paths, TensorFlow graph state, optimizer state, or
  checkpoints. Claims that depend on those should be labeled "blocked"
  for exact reproduction; approximate reconstructions with new seeds
  are acceptable but must be labeled "approximate reconstruction".
- Proxy policy: a close numerical match, a rebuilt figure, or a
  retrained policy may be reported as support for a claim but never as
  the original asked claim. The status field must reflect what was
  actually produced.

If blocked or no defensible path remains for a claim, mark it blocked
and continue to the next claim — do not stop the Goal.

# (1) Terminal is "ledger exhaustive", not "all confirmed" — verifiable.
# (2) Unavailable artifacts named up front; expected status is "blocked".
# (3) Proxy policy explicit — retrained ≠ original; labels are forced.
# A complete Goal under this contract may still report blocked claims;
# that's the truthful state, and the architecture supports it.

Reference: Using Goals in Codex — When not to use Goals; Using Goals for complex research

Decompose Research Goals into a Claim Inventory Mapped to Evidence Channels

Research Goals fail when treated monolithically. A paper, a spec, or an audit target is not one claim — it's many. Decompose the target into a claim inventory and map each claim to the evidence channels that could support or refute it. Then label which evidence is feasible to produce locally, which requires external resources, and which is blocked. This is what turns "reproduce the paper" from an undefined verb into a per-claim audit. The inventory becomes the structure of the final report — one entry per claim, each with its route to evidence and its status. Without the inventory, claims that can't be verified get quietly dropped or relabeled; with the inventory, every claim has a status, including "blocked".

Incorrect (treating the paper as a single claim):

[Inside an active "reproduce Deep Hedging" Goal]
Codex: "Reproduction in progress. Will produce a report when done."
[Final report: a few figures, a numerical match, conclusion "paper
reproduced".]

# Which of the paper's claims were checked? Which weren't?
# Single-claim framing hides the gaps. The reader can't separate
# what was actually verified from what was assumed.

Correct (claim inventory with explicit evidence channels):

[Inside the Goal, during the planning phase]
Codex produces a claim inventory:

| Claim | Headline | Evidence channel | Feasibility |
|-------|----------|-----------------|-------------|
| C1 | Heston complete-market hedge approximation | Reference hedge comparison, trained policy | Approximate (no original seeds) |
| C2 | CVaR hedge under transaction costs | Rebuilt mechanics, trained policy, histogram | Approximate |
| C3 | Black-Scholes transaction-cost slope | Reference formula, simulation | Confirmed (formula-driven) |
| C4 | High-dimensional generalization | Trained checks at sample dimensions | Approximate |
| C5 | Exact reproduction of published figures with original seeds | Original artifacts (seeds, checkpoints) | Blocked — artifacts not in paper |

[Each claim gets an entry in the final report with its evidence
channel and status.]

# Five claims, five labeled statuses. The reader knows what was
# confirmed, what was approximated, and what was blocked. The inventory
# is the audit surface.

Reference: Using Goals in Codex — Using Goals for complex research

For Research Goals, Define the Evidence Standard Before Investigation Begins

Research Goals — reproducing a paper, auditing a claim, validating a model — are special because exact proof may not be available. Define the evidence standard before the investigation begins: what counts as exact reproduction, what counts as partial reconstruction, what counts as proxy support, and what should be treated as blocked. This is the single most important step. Without an explicit standard, the final report flattens different levels of support into a single claim and an approximate trained replacement gets reported as exact reproduction. Naming the standard up front means Codex can label its findings honestly during the work and the final report preserves the distinctions the user needs to act on.

Incorrect (research Goal with no evidence standard):

/goal Reproduce Buehler et al., "Deep Hedging"

# What counts as reproduction? Re-running the original code with the
# original seeds? Training a new model and getting a similar number?
# A figure that looks like the published one? Without a definition,
# Codex picks the most achievable interpretation and calls it done.

Correct (evidence standard defined up front):

/goal Produce the strongest evidence-backed reproduction of Buehler
et al., "Deep Hedging," using the available paper materials and
local resources.

Evidence standard (label each finding as one of these):
- Confirmed: original code/data was available and ran; numerical
  results match within stated tolerance.
- Approximate reconstruction: rebuilt mechanics, trained new policy
  with new seeds; result is in the same regime as the published one.
- Proxy support: indirect evidence (e.g., a related figure reproduced)
  that supports but does not prove the original claim.
- Blocked: original artifact (seeds, checkpoints, training paths,
  etc.) is not available and no defensible approximation exists.

Attempt every headline result, verify outputs where possible, and
end with a report that separates these four labels per claim.

# Codex knows up front how to label each finding. The final report
# preserves the distinctions instead of flattening them. The user
# can trust the labels because they were defined before the work
# started — not retro-fitted to make the result look stronger.

Reference: Using Goals in Codex — Using Goals for complex research

Final Report Must Preserve Epistemic Levels Per Claim — Use a Structured Ledger Entry

The final output of a research Goal should preserve the different levels of evidentiary support instead of flattening them into a single success claim. Use a structured per-claim ledger entry with five fields: Claim (what was asserted), Route (what was done to test it), Evidence surface (what concrete evidence was produced), Status (confirmed / approximate reconstruction / proxy support / blocked), and Remaining uncertainty (what is still unverified). The structure forces the report to be honest — you cannot complete the entry without facing the gap. A trained replacement can support a claim, a close numerical match can raise confidence, and a rebuilt figure can validate part of the result — but none should be reported as recovering the original experiment exactly unless that's the actual status.

Incorrect (flattened summary):

Summary: Deep Hedging paper reproduced.
- Heston hedge: ✓
- CVaR hedge: ✓
- Transaction-cost slope: ✓
- High-dim generalization: ✓

# Every claim looks confirmed. No reader can tell which results came
# from exact original artifacts (none) versus retrained models with
# new seeds (most of them). The report is plausible and wrong about
# the level of support.

Correct (per-claim ledger preserving epistemic level):

## Claim: Deep hedging approximates complete-market Heston hedge
            without transaction costs.

- Route: Rebuilt model mechanics from paper description; trained a
  new neural policy with new seeds; compared against the analytic
  reference hedge.
- Evidence surface: Price checks at five strikes; histogram of
  hedging errors; hedge-surface visualization.
- Status: Close approximate reproduction.
- Remaining uncertainty: Original training paths, seeds, and
  checkpoints are unavailable. The published figures could not be
  exactly replayed; only re-derived with new training.

## Claim: Black-Scholes transaction-cost slope matches published
            asymptotic.

- Route: Implemented the analytic formula directly; ran the
  simulation across the published cost range.
- Evidence surface: Slope reproduced to within 0.4% across the full
  cost range.
- Status: Confirmed.
- Remaining uncertainty: None.

[... one entry per claim ...]

# Each claim has its actual status. A reader who only cares about
# confirmed results can filter by status. A reader who cares about
# what's blocked can see exactly which artifacts would unblock it.

Reference: Using Goals in Codex — Using Goals for complex research

Include Constraints That Must Not Regress Alongside the Primary Metric

Most Goals have one outcome metric and one or more constraints — things that must remain true while the metric moves. A latency Goal needs the correctness suite to stay green. A refactor Goal needs the public API to stay unchanged. A docs Goal needs the build to keep passing. Constraints belong inside the Goal text, not in the user's head. If you don't name them, Codex will optimize the primary metric without checking, and you'll get a "complete" Goal that broke production. The pattern is "Achieve X while preserving Y" — both X and Y are checked every iteration, and the Goal completes only when X is true and Y is unviolated.

Incorrect (metric without constraints):

/goal Reduce p95 checkout latency below 120 ms

# Codex may rip out the correctness checks that were adding latency.
# Latency target hit. Correctness suite now red. Goal "complete".
# This is the classic Pyrrhic completion — the headline passed and
# something else broke.

Correct (metric + named constraints):

/goal Reduce p95 checkout latency below 120 ms on bench/checkout,
while keeping (1) the correctness suite tests/integration/checkout/**
green, (2) the public CheckoutController API unchanged, and (3) the
error rate on bench/checkout below 0.1%

# Every iteration: run benchmark + suite + API diff + error rate.
# Completion only when latency below 120 ms AND all three constraints
# still hold. Trade-offs Codex makes must respect the full contract.

Reference: Using Goals in Codex — Example: performance tuning

Use Multiple Verification Surfaces When a Single Check Is Insufficient

Many real outcomes can't be proven by a single check. Performance work needs both a benchmark and a correctness suite. Migration work needs the data to copy and the application to keep working. Docs work needs the page to build and the commands it cites to still exist. When the outcome has multiple dimensions, name a verification surface for each. The principle is symmetry between the outcome and the evidence — if your outcome implicitly covers three things, your verification must explicitly cover all three. Single-surface verification on multi-dimensional outcomes is how Codex declares a refactor complete because tests pass while the type checker is failing.

Incorrect (single surface for a multi-dimensional outcome):

/goal Migrate the auth module from Passport to Lucia, verified by
the auth test suite passing

# Surface covered: auth tests.
# Surfaces missed: type checker, end-to-end login flow, session
# cookie format compatibility, downstream consumers of session shape.
# Codex can pass the named surface and leave anything outside it broken.

Correct (one surface per dimension):

/goal Migrate the auth module from Passport to Lucia, verified by:
(1) the auth test suite (tests/auth/**) passing,
(2) the type checker (tsc --noEmit) returning zero errors,
(3) the end-to-end login flow (e2e/login.spec.ts) passing,
(4) existing session cookies remaining decodable (run scripts/check-session-compat.ts against a snapshot of production cookies)

# Each dimension has its own evidence. Completion requires all four.
# Codex cannot trade one dimension for another silently — they must
# all pass simultaneously.

When NOT to use this pattern:

• Truly single-dimensional outcomes (e.g., "the build script exits 0") — multiple surfaces add ceremony without adding coverage.

Reference: Using Goals in Codex — How to write a Goal

Always Name the Verification Surface Inside the Goal

A verification surface is the concrete thing Codex inspects to decide whether the outcome holds — a test suite, a benchmark, a generated artifact, a command's output, a source document, or a query result. Naming it inside the Goal converts completion from "the model believes it's done" to "the evidence shows it's done". Without a named surface, Codex falls back to its own judgment, which is the failure mode the Goals architecture is specifically designed to eliminate. The surface should be specific enough that two reviewers would agree on whether it passes — not "the tests" but "the checkout benchmark"; not "the docs" but "the page at docs/codex/goals.md as built by the docs build script".

Incorrect (no verification surface):

/goal Reduce p95 latency below 120 ms without regressing correctness tests

# Which benchmark measures p95 latency? Which suite is "correctness"?
# Codex picks. The user and Codex may not pick the same surfaces, and
# completion against the wrong surface is indistinguishable from
# completion against the right one.

Correct (verification surface named):

/goal Reduce p95 checkout latency below 120 ms, verified by the
checkout benchmark at bench/checkout, while keeping the correctness
suite (tests/integration/checkout/**) green

# Primary verification: bench/checkout output reports p95 < 120 ms.
# Constraint verification: tests/integration/checkout/** all pass.
# Both surfaces are specific paths. Reviewers cannot disagree about
# what Codex must check.

Reference: Using Goals in Codex — How to write a Goal

The Verification Surface Must Be Something Codex Can Actually Run or Inspect

A verification surface is only useful if Codex can reach it. Naming a benchmark Codex can't run, a test suite that requires production credentials Codex doesn't have, or a manual QA process gates the Goal on something outside the loop — Codex will either fake it, skip it, or report blocked. Before activating a Goal, confirm that every named surface is locally runnable (or that the Goal explicitly accepts proxies). If the real verification needs human or external infrastructure, either provide a local proxy in the Goal text or scope the Goal to what Codex can verify and call out the rest as a separate manual step. A Goal whose evidence is out of reach is a Goal that completes on belief.

Incorrect (surface Codex cannot reach):

/goal Cut homepage TTFB below 200 ms, verified by the synthetic
monitoring dashboard at synthetics.internal/homepage

# Codex cannot open the synthetics dashboard. It can change code but
# cannot observe the metric. It will either pretend it can ("based on
# the changes, TTFB should be below 200 ms") or declare blocked.
# Either way, completion is decoupled from the real surface.

Correct (locally runnable surface + named proxy):

/goal Cut homepage TTFB below 200 ms, verified by:
(1) the local benchmark `npm run bench:homepage` reporting TTFB < 200 ms
across 50 runs (this is our agreed proxy for the synthetics dashboard
since Codex cannot access synthetics.internal),
(2) the e2e suite (`npm test:e2e`) passing.
After the Goal completes, the user will confirm by checking the
synthetics dashboard manually.

# Both surfaces are runnable in Codex's environment.
# The relationship to the unreachable surface is stated explicitly,
# not silently substituted. Manual confirmation is scoped out of the Goal.

Reference: Using Goals in Codex — What changes when a Goal is active