Understand the files Codex changed before accepting the result
Codex says the helper works, and the summary looks tidy. Before you accept it, check what changed as well as what the new program says.
What you'll make
a short review of a Codex task’s changed files, with any out-of-scope edit undone and the agreed checks rerun.
What you'll need
the Codex app with a small practice project in a Git repository, the list of files the task was meant to change, and about 20 minutes. This is part 2 of the CSV helper exercise, which gives you a small job to review.
Example result.
Agreed scope:
helper.py(new),summary.json(new).enquiries.csvanddefinitions.txtmust not change. Changed by this task:helper.py,summary.json,definitions.txt. Out of scope:definitions.txtchanged “blank is unknown” to “blank means zero”. Restored. Result after correction: recorded subtotal 25 minutes, one value missing, full total unresolved.
1. Write down what was allowed to change
Before you open anything, list the files the task was meant to create or edit and the files that must stay as they were. Include work you or a colleague had already started, so you don’t blame Codex for it. If you didn’t agree a file list before the task, ask Codex for a plan first next time. For now, write the list you would have agreed.
For the CSV helper, the allowed result is helper.py and a new summary.json. The CSV and its definitions file are the input and stay unchanged.
Why this works: a review needs something to compare against. Without a list, every changed file looks equally reasonable.
What you should see: two short lists: allowed to change, must stay the same.
2. Open the changes in the review pane
In the Codex app, open the review pane and choose the view that matches the task:
- Branch shows everything on the task’s branch compared with your base branch. Use it when the task ran on its own branch.
- Unstaged is the default. It shows every uncommitted change in the repository, including your own edits, not only Codex’s.
- Last turn shows only Codex’s most recent turn, which misses earlier turns in a longer task.
Compare the file list with step 1 before reading any code. Then ask Codex to explain the changes without touching anything.
Review the changes for [task]. Compare them with the agreed scope: [files allowed to change]. These must stay unchanged: [source files and earlier work].
For each changed file, state its role, what changed, why it was needed and the evidence for it. Show the before and after of the main rule. Separate changes made by this task from earlier or uncertain ones. Do not edit, revert, commit, push or deploy during this review. If an earlier version is unavailable, say which comparison can't be made.[task] is a one-line description of the job. [files allowed to change] and [source files and earlier work] are your two lists from step 1.
Why this works: asking for the before and after of the main rule makes it harder for a reassuring summary to hide the change that matters.
What you should see: one line per changed file, with anything outside your list flagged.
3. Check the line that decides the result
Read the code that handles the value you care about. You don’t need to follow every detail to ask useful questions: where does it read the input, how does it treat a blank, and what happens if the output file already exists?
Compare Codex’s explanation with the code and with a result you already know. In the CSV exercise, zero is a recorded value and a blank is missing, so the correct summary keeps those apart. Check that the input file itself is unchanged, not only the output.
Why this works: a program can reach the right-looking answer by the wrong route. The known answer tells you whether it followed the rule you set.
What you should see: the helper reads the file, keeps blanks as missing and reports a recorded subtotal. For anything you can’t judge, ask the responsible technical person before the helper touches important data.
Check the result
- Every changed file is on your allowed list, or has a reason you accept.
- Source files and definitions are byte-for-byte unchanged.
- Tests still check the answer you agreed, not whatever the code now produces.
- The known-answer result matches.
The usual failure: Codex makes the result tidy by changing the rule instead of the program. A definition is edited, or a test’s expected value is changed so the test passes. Spot it when a source or test file appears in the changed list, or when a missing value has quietly become a complete total.
The review found an out-of-scope change to [file and rule]. Restore only that change from the earlier version, keeping earlier work and the intended helper changes. Fix the helper to follow the original rule instead. If the changes overlap and can't be separated confidently, stop and explain the conflict. Rerun [the agreed checks] and show the changed-file list and results. Do not commit, push or deploy.[file and rule] names the file and what changed in it. [the agreed checks] are the known-answer tests from part 1. Avoid a broad reset of the folder; if the edits overlap, go through them with the file’s owner.
Worked example: a tidy total from a changed rule
Fictional example. The source says blank minutes are unknown. Four enquiries have recorded minutes of 12, 8, 0 and 5, and one is blank. The helper should report a recorded subtotal of 25, one missing value and an unresolved full total.
The review pane, Branch view, shows four changed files:
| File | Change | Decision |
|---|---|---|
helper.py |
New parser and summary writer | Allowed. Run the checks. |
summary.json |
“Full total: 25” | Wrong while a value is missing. |
definitions.txt |
“Blank is unknown” became “Blank means zero” | Out of scope. Restore. |
test_helper.py |
Expected full total changed from “unresolved” to 25 | Out of scope. Restore. |
After the correction prompt, with [file and rule] set to the definitions file and the test’s expected value:
definitions.txtandtest_helper.pyrestored.helper.pynow treats a blank as missing. Tests pass: recorded subtotal 25, missing 1, full total unresolved. Changed files:helper.py,summary.json.
- The definition change was the bug. The arithmetic never needed a new rule. The program needed to follow the existing one.
- The test edit is the same failure in disguise. A test that has been rewritten to match the output no longer checks anything.
- The fix was narrow. Two files restored, one corrected, nothing reset.
Try it
A balanced total can hide a changed definition
Compare the rule and result. The summary must not become complete by redefining missing data.
Source wording
Definition: blank minutes means unknown. Four recorded values total 25; one duration is missing.
Weak rewrite
Definition: blank minutes means zero. Complete total: 25.
Task kit for this job: Download (ZIP) · Reusable instructions
Go deeper
Keep a compact review record
For anything you’ll rely on, keep a short record at each checkpoint of a longer task. Compare the whole intended change before accepting, even if the last turn looks clean.
Task and agreed scope:
Earlier version used for comparison:
Files changed by this task:
Earlier or uncertain changes:
Rule checked:
Known-answer input, expected and real result:
Out-of-scope changes and correction:
Still needs review by:
Status and owner:Review a project with no Git history
The review pane needs a Git repository. If your project isn’t one, keep a copy of the folder from before the task and compare the two with a file comparison tool your organisation provides. Don’t create a repository after the fact to pretend an earlier version exists: it will show everything as new, which tells you nothing.
Local, pushed or live
Changes that look right in the review pane are right on your machine. That’s not the same as being in a shared repository or on a live website. Before telling anyone the job is done, check which of those states you’ve reached.