# A review from a fresh session

> Give the due-dates branch to a new agent session with the diff, the spec and the criteria, ask only for gaps against the spec, check each finding before acting on it, and sort the findings into ones to fix, ones to reject and ones to turn into a rule, while the gates still decide the merge.

Page: https://schubergphilis.github.io/ai-training/coding-with-agents/review-in-a-fresh-session/
License: CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/

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
(Best practices for Claude Code, Claude Code documentation).

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
(Best practices for Claude Code, Claude Code documentation). In Claude Code you can open a new session
in a second terminal, or run `/clear` to empty the current one before the
review (Best practices for Claude Code, Claude Code documentation). 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 (Create custom subagents, Claude Code documentation). 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
(Create custom subagents, Claude Code documentation). 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 (Best practices for Claude Code, Claude Code documentation).

#### Checkpoint: 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.

## 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
(Best practices for Claude Code, Claude Code documentation). 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
(Best practices for Claude Code, Claude Code documentation).

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)

```text
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

````text
```text
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: 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.

## 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: 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`.

```sh
python3 check_findings.py
```

Output:

```text
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
```

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](https://schubergphilis.github.io/ai-training/coding-with-agents/project-instructions/#fix-it-once-in-the-file)
  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`:

```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 the seven findings

Buckets:

- Fix in this change
- Reject
- Fix, and add a line to AGENTS.md

Items:

- 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

#### 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: 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.

## 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.

```sh
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
(How Claude remembers your project, Claude Code documentation). Manual mode, which the flag selects, lets the agent
read files without a prompt (Choose a permission mode, Claude Code documentation). 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 (Configure permissions, Claude Code documentation). 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 (Best practices for Claude Code, Claude Code documentation).
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 (Best practices for Claude Code, Claude Code documentation).
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.

#### 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

- Best practices for Claude Code, Claude Code documentation, https://code.claude.com/docs/en/best-practices
- Create custom subagents, Claude Code documentation, https://code.claude.com/docs/en/sub-agents
- How Claude remembers your project, Claude Code documentation, https://code.claude.com/docs/en/memory
- Choose a permission mode, Claude Code documentation, https://code.claude.com/docs/en/permission-modes
- Configure permissions, Claude Code documentation, https://code.claude.com/docs/en/permissions