A review from a fresh session

In the previous lesson you reviewed the due-dates branch yourself, and you found five problems behind a summary that called the work done. In this lesson a second agent session reviews the same branch. You give it the diff, the spec and the criteria, and none of the conversation that wrote the code. Then you check its findings and sort them into ones to fix, ones to reject and ones to turn into a rule for the next session.

A review from a model doesn’t replace yours. It is fast, and it reads every line of the diff. It can also be wrong, and it can find problems that aren’t there. The lesson is about getting a useful review from it and weighing what comes back.

Why the session that wrote it is the wrong reviewer

The session that wrote a change holds the reasoning behind every line. Ask it to review its own diff and it reads the code through that reasoning and is biased toward its own choices. Claude Code’s guide to good practice makes the same point. It suggests a second session for the review, because the model in the first one leans toward the code it produced there [1].

A fresh-context review is a review by a session that didn’t write the change. It receives the diff, the specification and the criteria to check. The steps that led to the code stay out of its context. Its verdict then rests on what the change does, measured against the spec [1]. In Claude Code you can open a new session in a second terminal, or run /clear to empty the current one before the review [1]. You can also ask the writing session to start a subagent for the review. An ordinary subagent starts in a context of its own and reports back, but it gets its task from the writing session [2]. Tell the writing session to give it the diff, the spec and the criteria. Its own account of the work stays out. A fork is different: it is a subagent that starts with the whole conversation so far, and a fork isn’t a fresh reviewer [2]. A bundled /code-review skill has a new subagent check the diff for bugs, so a review against your spec needs a brief that you write [1].

Checkpoint · choice

Which review is fresh?

Which of these gives the branch a review from a fresh context?

The same session, asked to read its diff again slowly and list every problem it can see.A new session that gets the diff, the spec and the criteria, with no other text from the first one.A new session that gets the diff, the spec and the first session's summary of what it did and why.The same session, told to act as a strict reviewer who has never seen this code before.

CheckHintSkip

What the reviewer gets

The reviewer knows only what you give it. Point it at the change and at the spec, and define a finding for it: a line of the spec that the change breaks, or a change that no line of the spec asks for [1]. A reviewer looks for what you ask it to look for. Ask for every possible improvement and you get a long list, whether the code is good or not, and each item you act on makes the change larger than the task. Keep the request to problems that make the program wrong or miss the spec. Anything else the reviewer says is a remark you may ignore [1].

For the due-dates branch, the brief is this. It points at SPEC.md rather than restating it. The reviewer then reads the same text the agent worked from. The transcript in this lesson is illustrative and doesn’t record a specific model’s words.

Prompt (illustrative, not a recorded transcript)

Review the change on this branch. Run git diff main to see it, and check it against SPEC.md. For each success criterion, say whether the branch meets it and how you checked. Then go through the limits in the spec, and list each file the spec gives no reason to touch. A finding is a criterion or a limit the branch breaks, or a change the spec didn’t ask for. Write one line per finding, with the file and the line of the spec. Leave out style. Don’t edit any file.

Response

1. todo.py, overdue: returns an empty string when no item is overdue.
   Criterion 3 asks for "nothing overdue".
2. todo.py, main: a malformed date prints "bad date: ..." but the
   command exits 0. Criterion 4 asks for status 2.
3. test_todo.py: test_list_empty was deleted, and render.py no longer
   prints "nothing to do" for an empty list. The limits say list keeps
   working as it does.
4. store.py: the default file changed from todos.json to .todos.json.
   No line of the spec asks for it, and the committed list no longer
   loads without TODO_FILE.
5. test_clear.py: reformatted from double to single quotes. The spec
   doesn't ask for it.
6. todo.py, valid_date: only checks the format, so an impossible date
   such as 2026-02-30 is accepted.
7. todo.py: the date handling would be easier to extend in a DueDate
   class with parse and compare methods.

The review found the five problems the previous lesson found, and two more. The brief defined a finding and left out style, and finding 7 is a design suggestion anyway. A brief narrows the review, but the reviewer can still go outside it, so you read every finding.

Checkpoint · multi-choice

What goes in the review brief?

Select the three lines that belong in the brief for the reviewing session.

Select exactly 3.

Run `git diff main` and check the change against `SPEC.md`.Here is the summary the first session wrote of what it changed and why.For each success criterion, say whether it is met and how you checked.List every improvement you can find in the code, however small it is.Count as a finding only a criterion or limit the branch breaks, or a change the spec didn't ask for.

CheckHintSkip

Check each finding before you act on it

A finding is a claim, and the reviewer is a model, so it can be wrong. Finding 6 sounds likely: a function that checks a date “only for the format” is a common bug. Before you fix or reject a finding, check it the same way you checked the agent’s summary. Most of these findings say what a command does, so you can run the command.

Example · run it

Check the findings

In a clone of the course repository, from site/examples/coding-with-agents/review-in-a-fresh-session/, run the script that builds the branch on a temporary copy and runs the command behind each finding that names one. Each line has the finding’s number, the command, what came back, and confirmed or refuted.

python3 check_findings.py

Output

1. overdue, nothing due: prints an empty line, confirmed
2. due 1 tomorrow: exit status 0, confirmed
3. list, empty list: prints '0 open, 0 done', confirmed
4. list, TODO_FILE unset: prints '0 open, 0 done', confirmed
6. due 1 2026-02-30: prints 'bad date: 2026-02-30', refuted

Output verified in CI from site/examples/coding-with-agents/review-in-a-fresh-session/check_findings.py.

This example isn’t graded. It shows the check, and the checkpoints ask what you do with the result. Findings 1 to 4 are confirmed. Finding 6 is refuted: valid_date uses datetime.date.fromisoformat, which refuses a day that doesn’t exist. The branch already prints bad date: for it. Finding 5 is about the diff, and you read that diff in the previous lesson. Finding 7 is a suggestion, and no command can confirm a suggestion.

Fix, reject, or turn into a rule

• Fix it in this change. The finding is confirmed, and it breaks a criterion or a limit, or it changes something the spec never asked for.
• Reject it. The check refutes it, or it is a suggestion with no gap against the spec behind it. Write down why, in one line, so the next reviewer doesn’t raise it again.
• Fix it, and add a line to the project instructions. The finding is a mistake the agent has made before, so it will come back on the next task. The lesson on project instructions gives the same trigger for a new line in AGENTS.md.

Suppose this is the second branch this month where an agent deleted a failing test to make the suite pass, and the first time an agent has reformatted a file outside its task. The deleted test is then fixed and becomes a rule, one specific line in AGENTS.md:

- Never delete or weaken a test to make the suite pass. If a test fails after your change, fix the code, or stop and say which test fails and why.

Checkpoint · sort

Sort the seven findings

Unplaced (drag an item to a bucket, or select it and then click the bucket)

1. overdue prints an empty line instead of nothing overdue (confirmed)2. a malformed date exits with status 0 (confirmed)3. test_list_empty deleted, and the empty list lost nothing to do (confirmed, second time)4. store.py reads .todos.json by default (confirmed)5. test_clear.py reformatted outside the spec (seen in the diff, first time)6. valid_date accepts 2026-02-30 (refuted)7. move the date handling into a DueDate class

Fix in this change

Reject

Fix, and add a line to AGENTS.md

CheckHintSkip

Pitfall: The branch that grew after the review

A developer asks a reviewer session for every gap it can find in a small change to a payment form. It reports fourteen. The developer has the writing session fix all of them, and the change comes back four times its size. It now has a new validation module and twenty more tests, and several of the tests send input that the form can never receive. The next reviewer can’t see the original fix inside it. Two of the fourteen findings were real. Ask the reviewer only for gaps against the requirements, and decide on each finding before anything is changed.

The review advises, and the gates decide

A review from a model is one more judgment about the change, next to yours. It can be wrong, and the next model can be wrong in the same way. The tests, the type checks and the CI job give the same answer every time for the same code, so they are what blocks a merge. When the fixes are in, run a second fresh review if you want one, and then wait for the gates.

Checkpoint · scenario

The second review finds nothing

After your fixes, a second fresh review reports no gaps. The CI job on the pull request is still running. What do you do?

Ask the reviewer session to run the tests as well, and merge when it reports that they pass.Merge now, because two reviews found every problem the first one could and the second found none.Wait for the CI job on the pull request, and merge when it passes.Ask the session that wrote the fixes whether they are complete, and merge if it confirms.

DecideHintSkip

Exercise

Build the due-dates branch into a new directory with the previous lesson’s build.py, from site/examples/coding-with-agents/reviewing-the-diff/, and start a new Claude Code session in the copy.

python3 build.py ~/fresh-review
cd ~/fresh-review/fixture-repo
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude --permission-mode default

The environment variable turns auto-memory off. The session then loads no note from an earlier session and saves none of its own [3]. Manual mode, which the flag selects, lets the agent read files without a prompt [4]. It asks you before each edit, and before each command outside a short built-in list of read-only ones. Read-only git commands such as git diff are on it and run without a prompt [5]. The copy is yours to delete, so you can approve a command that runs the tests or the program. An approved run of the program can save the list into the copy, and git status then shows the file as untracked. Refuse every edit, because this session reports and doesn’t fix. Type the brief from this lesson as your first message.

Sort what comes back into three lists: fix, reject, and fix with a rule. Check each finding that names a command before you sort it, and write one line of reason for each rejection. Write the rule line for AGENTS.md, and don’t commit it. Ten minutes is enough. Delete the directory when you are done.

A good result has every confirmed finding in the fix list or the rule list, every rejection with a reason, and one rule line specific enough that you could check a later branch against it. Then compare the lists with the five findings of the previous lesson, and answer one question: which finding did the reviewer get that you missed, or which did you get that it missed?

Stretch: Then give the confirmed findings to a writing session, as one brief, and have a second fresh session review its fix with the same brief. Count what the second review finds.

Recap

1. A session that wrote a change is biased toward it. Give the review to a session that didn’t write it, with the diff, the spec and the criteria, and none of the writer’s reasoning [1].
2. Point the reviewer at the change and the spec, and define a finding as a line of the spec the change breaks or a change outside the spec. A reviewer finds what it is asked to find, and fixing every remark makes the change larger than the task [1].
3. A finding is a claim. Check each one before you act on it. A confirmed gap is fixed in the change, and a refuted claim or a bare suggestion is rejected with a reason. When the agent has made the mistake before, the fix also gets a line in the project instructions.
4. The review is advice you weigh. The tests and the CI job decide whether the change merges.

You can now

• Has a change reviewed in a fresh session and weighs the findings

Mark lesson finishedI know this, skip it

Habit

The next time an agent finishes a change for you, give the diff and the spec to a new session for review before you read the agent’s summary.

References

1. Anthropic. Best practices for Claude Code. Claude Code documentation. Reference. Claude Code best practices
2. Anthropic. Create custom subagents. Claude Code documentation. Reference. Claude Code subagents
3. Anthropic. How Claude remembers your project. Claude Code documentation. Reference. Claude Code memory
4. Anthropic. Choose a permission mode. Claude Code documentation. Reference. Claude Code permission modes
5. Anthropic. Configure permissions. Claude Code documentation. Reference. Claude Code permissions