Break: first workflow review

What to understand

• The reviewed workflow is one loop with six named stages: SCOPE -> BRIEF -> PROPOSE-DIFF -> REVIEW -> APPROVE -> VERIFY. Scope decides the smallest change worth making; the brief (Lesson 5) is the contract; propose-diff means the agent shows the change without applying it; review is you reading that change like a pull request; approve is your explicit 'go' on what survives; verify is running the acceptance check from the brief. Every stage has a job, and skipping any one of them is where runs go wrong.
• Propose-diff is the heart of the loop, and both tools build it in. Claude Code's plan mode (Shift+Tab to cycle into it, or /plan) reads your codebase, reasons through the approach, and presents a numbered plan plus the intended changes while making zero edits, you review intent before any file is touched. Codex's app shows a diff pane for uncommitted/staged/branch changes where you inspect each hunk, drop inline comments on specific lines, and stage, unstage, or revert at the level of a whole diff, a single file, or one hunk. In both, the agent proposes; you dispose.
• Review the proposed change exactly as you'd review a colleague's pull request, because that is literally what it is. OpenAI's own guidance is to 'treat Codex suggestions like any other PR: run targeted verification, review diffs, and document decisions in commit messages.' Read every hunk, confirm each one traces to something in your brief, and flag anything you didn't ask for. The diff is your review surface, not the agent's prose summary of what it claims it did.
• Approval is consent to a specific change, not a vibe. 'Looks good' after skimming is not review; approving each hunk because you understand why it exists is. Codex lets you stage/revert per hunk so approval can be partial, keep the three hunks that match the brief, revert the one that 'helpfully' renamed a variable. Partial approval is a feature, not an inconvenience: it's how you accept the change you wanted without the collateral you didn't.
• Verification is the stage beginners skip and operators never do. OpenAI states it plainly: 'Don't stop at asking Codex to make a change. Ask it to create tests when needed, run the relevant checks, confirm the result, and review the work before you accept it.' The acceptance command you put in the brief (Lesson 5) is what you run here, and you run it yourself, or watch the agent run it and read the real output, rather than trusting a summary line that says 'all tests pass'.
• A silent failure is the run that reports success while being wrong, incomplete, or out of scope, and it is the failure mode that costs the most because nothing alerts you. The four common shapes: (1) the diff looks plausible but doesn't actually fix the bug; (2) the agent edited files outside the scope you set (scope creep); (3) a test was added that passes without actually testing the behaviour, or an existing failing test was weakened to make it green; (4) the work is 80% done and the missing 20% is exactly the failure-handling, edge case, or non-functional requirement you cared about. Each is invisible if you only read the agent's 'done' message.
• Catching silent failures is a verification skill, not a trust skill. You catch them by: reading the diff against the brief's acceptance criteria line by line; running the verification command yourself and reading the actual output; checking that any new test would FAIL on the unfixed code (a test that passes before and after the change tests nothing); and scanning for any file touched that your scope-out line forbade. 2026 benchmarks (SpecBench, the Reward Hacking Benchmark) measure exactly this gap, the difference between an agent's reported success and its real held-out success, and the operator's defence is the same in every case: verify the claim, don't accept it.
• After the run, a short reflection compounds the gains. Reviewing your own workflow is the same discipline as reviewing code: compare the result against the intent and look for the gap. Most agent disappointments are input problems, a vague brief, a missing constraint, a wrong scope, not model failures, so the reflection focuses on the one input you'd change next time, and where to record it so it persists.
• Capture the learning where it survives the session. A one-off correction typed into chat is forgotten next session; the same rule added to CLAUDE.md / AGENTS.md is read every time, automatically, before the agent starts. The reflection's whole job is to convert today's surprise into tomorrow's standing instruction, promoting a one-task correction into a permanent convention is what makes run N+1 measurably better than run N.
• Keep the loop short and repeatable. The reviewed run plus a three-question reflection, did it meet the criteria, what was the weakest input, what one change improves the next run, takes a couple of minutes and compounds across dozens of tasks. Going faster with a loose loop just produces wrong results faster; a tight propose-review-verify loop is what makes speed safe later in the course.

Deeper dive

Propose-and-review controls compared (Claude Code vs Codex, June 2026)

How each tool implements the propose-diff -> review -> approve stages of the loop. These are the surfaces you'll drive in the hands-on. Both tools ship fast; command names and defaults change, verify at the official docs linked below before relying on specifics.

Sources (as of June 2026): Claude Code. Best practices (plan mode, review-first) · Codex. Review (diff pane, inline comments, /review) · Codex. Best practices (verification, treat output like a PR)

Step by step

1

Scope the smallest real task and write the brief

12

Pick one genuinely small task from your own work, a single-file bug fix, a tiny helper plus its test, one config change. Resist bundling. Then fill in the reviewed-run brief (the first production prompt in this lesson): real file paths, an explicit scope-OUT line, a measurable 'Done when', and an exact verification command (prefer a RED-then-GREEN test). If you can't state the outcome in one sentence, the task is too big, split it before you start. Done when the template has no angle brackets left and the verification command is one you have actually run yourself.

HintThe smaller the scope, the cleaner the review. A 20-line diff is reviewable hunk-by-hunk in two minutes; a 300-line diff hides silent failures by sheer volume.

On this screen

1. 1Single-outcome ask. The screen shows a task already scoped to one outcome with verification built in (add a test, then run the linter). Notice what it is missing: a scope-OUT line, your brief adds the fence this example lacks.
2. 2Verification in the plan. Plan step 4 (Run the linter to validate) is the agent echoing the brief's check back, your RED-then-GREEN test command should appear in the proposed plan the same way.

2

Put the agent in propose mode and get the diff without applying it

12

Start the run in a propose-only posture so nothing is applied before you see it. In Claude Code, Shift+Tab into plan mode (or /plan), it reads the code and presents a numbered plan plus intended changes, making zero edits. In Codex, keep the sandbox read-only / propose-a-plan-first and use the diff pane to inspect uncommitted changes. The brief's WORKFLOW block already says 'show the diff, then STOP and wait for go', confirm the tool actually halted and is showing you a proposed change, not a completed one. In default mode you will see a per-edit approval like the one shown; plan mode moves that same gate earlier, so you approve the whole plan before any edit is even proposed.

HintPropose mode is the 30-second insurance that catches the 'why is it touching that file?' moment before the file gets touched. Reviewing intent is cheaper than reverting a mistake.

On this screen

1. 1Proposed diff, not yet applied. The + lines are a proposal at this moment, nothing is on disk until the question below is answered.
2. 2The gate question. Do you want to make this edit? is the propose-act gate in default mode, the Applied line only happens after a Yes. Plan mode lifts this same gate to the front of the run. If edits appear with no question asked, your gate didn't fire: fix the mode and re-run.

3

Review the diff hunk-by-hunk like a pull request

12

Go through the proposed diff one hunk at a time. For each hunk ask: which line of my brief does this serve? Keep hunks that map to scope-IN; question any hunk that maps to nothing; stop on any hunk that touches your scope-OUT. In Codex, hover a line and drop an inline comment on anything wrong ('outside scope, revert'); the comment becomes guidance for the next turn. Read the diff as the source of truth, treat the agent's prose summary as a claim to verify against the hunks, never a substitute for reading them.

HintThe hunk whose purpose isn't obvious is the one to question hardest, unexplained changes are where silent failures hide, not the scary-looking ones.

On this screen

1. 1Diff / review surface. Review here exactly as you'd review a teammate's PR, every hunk traces to a line of the brief or it's questioned.
2. 2Commit or push, last, not first. The commit control sits in the corner for a reason: nothing is committed until every hunk maps to a line of the brief. In the app, hovering any diff line offers a + to leave an inline comment Codex treats as guidance for the next turn.

4

Run a strict self-review pass before you approve

Before approving, run the second production prompt, the do-not-fix adversarial self-review, with your acceptance criteria and scope-OUT pasted in. Make it report (not fix): correctness gaps, tests that would pass on a broken implementation, scope violations, missing error-handling/edge-cases, and risks automated tests won't catch. Read its findings critically; you decide which are valid. Running this in a fresh context (a second pass) catches more than letting the implementer grade itself mid-stream. Expect back a numbered findings list with severities, ending in a one-line net recommendation, prose reassurance instead means the prompt was not followed; re-run it.

HintA 'do not fix, just report' framing gives you a review you can trust before you let the agent touch code again, and the silent-failure section is the part that earns its keep.

5

Approve selectively, then verify the result yourself

Approve only the hunks that survived review, keep the brief-matching ones, revert the collateral (Codex stages/reverts per diff, file, or hunk). Then VERIFY: run the brief's acceptance command yourself, or watch the agent run it and read the actual, unedited output. Confirm the RED-then-GREEN test really did go red on the old code and green on the new, a test that's green both before and after tested nothing. Do NOT accept on the strength of a 'done' message or a summary line.

HintVerification is the stage beginners skip and operators never do. 'All tests pass' in prose is a claim; the real test output is proof. Read the proof.

6

Reflect: criteria met? weakest input? one change?

Now the two-minute reflection. Answer three questions in writing. (1) Did the output meet every acceptance criterion and stay inside scope, met, partially met, or missed, field by field? (2) What single input most limited the result, a vague outcome, a missing constraint, no scope-OUT, a weak verification command? Name it plainly; you're diagnosing your brief, not the model. (3) What ONE change will you make next run? Keep it to one so you can tell whether it helped.

HintThere's almost always one input that, if fixed, would have changed the whole run. Find that one, and change only that one, so the next loop gives you a clean signal.

7

Promote the learning into a standing rule

Take the weakest input you found and decide where it lives permanently so it's never lost. If it's a project convention (locale, logging, 'always add a reproducing test'), add one line to CLAUDE.md / AGENTS.md, read automatically every session. If it's a one-task detail, fold it into your brief template. A correction you only said in chat is gone next session; a correction in CLAUDE.md / AGENTS.md is applied every time, before the agent starts. Confirm the promotion stuck: next session, /memory (or a diff of the file) shows the new line loaded before the agent starts.

HintThe reflection's whole job is to convert today's surprise into tomorrow's standing instruction. One promoted rule retires a class of mistake permanently.

Production prompt examples

ROLE: You are a senior engineer pairing with me in a careful, propose-first mode. I am the human in the loop and I approve every change before it is applied.

CONTEXT: <one or two sentences on the system and the exact problem>. Relevant files: <paths>. Project conventions: see CLAUDE.md / AGENTS.md and follow them.

SCOPE, IN: <the single outcome this task should achieve>.
SCOPE, OUT: Do NOT modify <files / systems / behaviours that must not change>. Do NOT add dependencies, change schema, or touch unrelated files.

CONSTRAINTS: Match the existing code style in the touched files. Keep the change minimal, the smallest diff that satisfies acceptance. Preserve existing logging and public behaviour.

DESIRED OUTCOME (Done when): <one measurable sentence describing the verifiable end state>.

ACCEPTANCE / VERIFICATION: Add a test that reproduces the problem and FAILS on the current code (RED), then make it PASS (GREEN). Before we finish, run `<exact test/lint command>` and show me the real, unedited output.

WORKFLOW, propose first, do not apply:
1. Work read-only. Show me (a) a one-line statement of the goal as you understand it, (b) the files you'll change and why, and (c) the proposed unified diff.
2. STOP after showing the diff. Do NOT write files, run state-changing commands, install, or touch git until I reply 'go'.
3. After I approve, apply ONLY the approved hunks, run the verification command, and paste the actual output.

OUTPUT: The proposed diff first; then, on my approval, the applied diff + the verification output + a one-paragraph note of anything you assumed or anything you could NOT verify.

ROLE: Act as a strict, adversarial code reviewer who did NOT write this change and is sceptical of it. Your job is to find problems, not to defend the work.

INPUT: The diff you just proposed, plus this brief's acceptance criteria and scope-out line:
- Acceptance: <paste the acceptance criteria>
- Scope-OUT (must NOT change): <paste the scope-out line>

REVIEW, report findings in order of severity, do NOT change any code:
1. CORRECTNESS: Does the change actually achieve the stated outcome? Name any case where it would NOT, and any acceptance criterion it does not fully meet.
2. SILENT FAILURES: Would the new/changed tests FAIL on a deliberately broken implementation? Flag any test that would pass regardless (asserts nothing, weakened assertion, skipped/removed test). Flag any 'success' that is reported but not actually verified.
3. SCOPE: List every file and behaviour changed that is outside the scope-IN, i.e. any violation of scope-OUT or any unrequested edit.
4. MISSING 20%: List error handling, edge cases, and non-functional requirements (logging, locale, performance, security) that the brief implies but the diff does not cover.
5. RISKS BEFORE COMMIT: Anything I should manually check that automated tests won't catch.

OUTPUT: A numbered list per section above. For each finding: file:line, one-line description, severity (CRITICAL / HIGH / MEDIUM / LOW). End with one line: 'Net recommendation: approve / approve-with-fixes / reject'. Do NOT modify anything, report only. I decide what's valid.

Common mistakes to avoid

• Accepting the agent's 'done' message and prose summary instead of reading the diff, the prose is a claim; the diff and the real test output are the evidence.
• Letting the agent apply changes before you've seen them, because you didn't put it in plan/propose mode, review-before-apply is the whole point of the loop.
• Skimming a large diff and clicking approve on the vibe, instead of mapping each hunk to a line of the brief and questioning the ones that map to nothing.
• Trusting 'all tests pass' without running the check yourself, a test that's green before and after the change, or an assertion quietly weakened, tests nothing.
• Missing scope creep because you never diffed the touched file paths against your scope-OUT line, the collateral edit is the most common silent failure.
• Treating the loud, scary-looking hunk as the risk while waving through the small unexplained one, unexplained changes are where silent failures actually live.
• Blaming the model for an outcome a clearer scope or a runnable acceptance criterion would have fixed, then reaching for a bigger model instead of a better brief.
• Correcting the agent only in chat so the learning evaporates, instead of promoting it to CLAUDE.md / AGENTS.md or the brief template.
• Listing ten things to improve at once, leaving you unable to tell which change actually helped the next run.

Source conflicts to review

• Plan-mode activation is described inconsistently across guides (Shift+Tab cycling vs typing /plan vs a defaultMode setting), all reported valid as of June 2026; confirm against code.claude.com.
• Codex's review surface and approval behaviour shift across point releases (inline-comment handling, smart approvals default-on since ~v0.120); treat the mechanics here as accurate as of June 2026 and re-check the official review page before relying on specifics.
• Reward-hacking / silent-failure exploit rates vary widely by model and by benchmark methodology (e.g. SpecBench's validation-vs-held-out gap, the Reward Hacking Benchmark's per-model rates from ~0% to ~14%); these are research findings on a moving target, not fixed product facts, cite the specific benchmark and date and don't generalise a single number across all models.