Review agent work

Review agent work the same way you review a teammate's branch, with one extra habit: check how the agent got there.

The terminal tells you what the agent said. The diff tells you what it did. The task tells you whether it mattered.

Start with the task

Before opening changed files, read the task description. Look for three things:

• What problem was the agent asked to solve?
• What was explicitly out of scope?
• What checks were expected?

If the task is vague, tighten it before asking for more work. A vague task usually becomes a vague diff.

Read the plan and session log

Open the latest implementation plan if the brew has one. You are checking direction, not grading prose.

• Did the agent touch the areas it said it would touch?
• Did it avoid the areas it said were out of scope?
• Did it name the right checks?
• Did the plan miss a risk that now appears in the diff?

The session log should explain what happened after the plan: files changed, commands run, failures, and follow-up the agent could not finish. A missing or fluffy session log is a reason to inspect more carefully, not a reason to reject the work by default. If the plan and diff disagree, trust the diff and investigate.

Open the changed files

Coldtea groups the branch's changes into a changed-files list, split into sections such as Staged Changes and the unstaged categories. You can stage a single file or stage everything, then open any file to see its diff.

Read the diff

Open the changed files and review them against the task. Look for ordinary engineering issues:

• The change solves the requested problem.
• The scope did not drift.
• The code follows local patterns.
• Tests cover the risky path.
• Generated files or lockfiles changed only when expected.
• Secrets, machine paths, or debug leftovers did not sneak in.

Agents are good at producing plausible code. Plausible is not the same as correct.

Comment on diff lines

You can leave a comment on a specific diff line. Open the comment input on the line, type the note, and save it. Each note attaches to the file and lines you picked, so the feedback stays anchored to the exact code.

Saved comments collect in a review dock at the edge of the editor. The dock shows a Comments toggle with a running count, so you can hide the panel while you keep reading and reopen it to see every queued note. Clear the queue when you want to start over.

For the full model of comments across the terminal, editor, and browser, see comments and annotations.

Send the comments to the agent

Diff comments stay queued in the editor until you send them. To act on them, open a Terminal pane and choose the agent that should take the next pass. Coldtea turns the queued comments into a single prompt, so the agent gets your notes with the file and line references intact.

This is the loop: read the diff, mark the problems inline, then hand the whole set to the agent in one message instead of retyping each note.

Run the checks

Use the smallest checks that prove the change:

npm run lint
npm run types:check
npm test -- path/to/relevant.test.ts

If an agent claims a check passed, read enough output to know which command actually ran and where it ran.

Commit

When a set of changes is ready, stage the files you want and commit them from the editor. The commit control needs staged files and a message before it will commit, and it shows how many files are staged so you commit the set you meant to.

Finish deliberately

A review ends in one of three ways:

• Accept the change and move it toward merge.
• Ask the agent or a teammate for another pass with focused feedback.
• Discard the branch because the direction is wrong.

Focused feedback names the exact problem and the expected fix:

The redirect still drops the query string. Preserve it when you rebuild the return URL, then rerun the auth tests.

Do not archive the context until you know which of the three happened.

Next: run parallel agents when work can be split into separate branches.