The handoff note an agent leaves

An invented scene, just to keep it concrete. You open your laptop and there's a finished agent run waiting from last night. The diff is clean. It moves session handling out of a controller and into its own module, updates the call sites, and adds tests that pass. Then you notice the old cookie path is still there, untouched. Did the agent leave it on purpose? Did it miss it? Is it half done? The diff can't tell you. So you spend the next half hour reading code to rebuild what the agent already knew when it stopped.

This is an opinion piece, so here's the claim up front. I think the most useful thing an agent run produces is often not the change. It's the short note the agent leaves at the end for whoever reads next. What it did, what it skipped on purpose, what it isn't sure about, and what it would check next. I also think the shape of that note belongs in the brief, before the run starts, not as something you ask for after you're already confused.

The diff shows what changed, not what was doubted

A diff is honest about one thing. It shows exactly which lines moved. That's a lot, and it's why we review diffs. But it's silent about everything around the change.

It doesn't show the file the agent opened, thought about editing, and decided to leave alone. It doesn't show the test it wanted to write but couldn't, because the fixture didn't exist. It doesn't show the moment it guessed at what an unclear function returned and kept going. Those are exactly the things the next reader needs, and they're the things that disappear when the run ends.

Between people, this gap gets filled in conversation. A teammate opens a pull request and says "I left the cookie path alone because the mobile client still uses it." That one sentence saves a reviewer from treating a deliberate choice as a bug. When an agent does the work, that sentence often never gets said. The agent had the reason. It just wasn't asked to write it down.

The next reader is usually in a worse spot than the agent was. Maybe it's you the next morning, a teammate picking up the branch, or a fresh agent session with none of the previous context. All of them start from the code alone. They can see what's there. They have to guess at what was considered and rejected, and a wrong guess is cheap to make and expensive to act on. A fresh session that reads the leftover cookie path as unfinished work will happily "finish" it.

What goes in the note

I don't mean a report. I mean four short parts, written in plain sentences, at the end of one run.

What I did. A few lines in the agent's own words, not a list of every file. "Moved session handling into its own module and updated the three controllers that call it." The diff already has the detail. This part just gives the reader a map before they open it.

What I skipped on purpose. This is the part I care about most. Anything the agent chose not to touch, with the reason. "Left the legacy cookie path in place. The mobile client still reads it, and removing it was out of scope." This turns a mystery into a decision the reader can agree or disagree with.

What I'm unsure about. Guesses, assumptions, and places where the agent filled a gap without proof. "I assumed the session timeout in config is the one production uses. I didn't find where it gets overridden." I think this is the part that's hardest to get from an agent without asking, and the most valuable when you get it. It tells the reviewer exactly where to aim their attention.

What I'd check next. The next step the agent would take if the run kept going. "Confirm the mobile client's cookie dependency before removing the legacy path." This is the thread the next reader picks up, so they don't have to find it themselves.

That's the whole note. It should fit on a screen. If it runs longer, either the run was too big or the note has turned into a diary. Neither helps the reader.

A made-up example of a whole note, for illustration only:

• Did: moved session handling into a new module, updated callers, added tests for login and logout.
• Skipped on purpose: the legacy cookie path, because the mobile client may still depend on it.
• Unsure: whether the timeout in config is the value production uses.
• Check next: the mobile client's cookie usage, then decide whether the legacy path can go.

Four lines. Someone reading that before the diff knows where the edges are, where the risk is, and what's still open.

Put the shape in the brief

Here's where I think most of the value comes from. If you only ask for a note after the run, you get whatever the agent feels like writing, in whatever shape it picks, buried wherever it lands. If you put the shape in the brief, you get the same four parts every time, in the same place.

That consistency matters more than it sounds. When every run ends with the same four headings, the reader stops hunting. They know the skipped list is where deliberate omissions live. They know the unsure list is where to look first. Review starts from the agent's own doubts instead of from the top of the diff.

It also changes the run itself, a little. An agent that knows it'll be asked "what did you skip on purpose" has a reason to notice when it's skipping something. An agent that knows it'll be asked "what are you unsure about" has a reason to mark a guess as a guess instead of smoothing over it. I won't claim more than that. But we've found that asking for the note up front, in plain words, gets a more honest note than asking afterward.

The brief doesn't need to be elaborate. A short closing section is enough. "When you finish, end with four short sections: what you did, what you skipped on purpose and why, what you're unsure about, and what you'd check next." Put it in the same place every time, and ask for the note in the same place every time, whether that's the end of the plan file, a short notes file next to the change, or the pull request description.

What the note is not

It's worth being clear about the edges, because this idea gets bigger than it should very quickly.

It isn't a team record. It covers one run, written by the agent that did the work, for the next reader of that work. A record of why the team made a call across many runs is a different thing, with a different owner and a longer life. The end note can feed it, but it doesn't replace it.

It isn't a status update. "Done" tells you the run stopped. The note tells you what state it stopped in.

And it isn't proof the work is right. A note can be wrong, especially in the "what I did" part. The agent can describe the change it meant to make rather than the one it made. The note is where you start reading, not a reason to stop. The diff still gets reviewed. The note just tells you where to look first.

Ask for the note, not just the change

Here's the reframe I'd leave you with. We tend to treat the change as the output of an agent run and everything else as exhaust. I think that has it slightly backwards. The change is what the agent did. The note is what it knew, and what it knew is the part that's gone once the run ends.

So when you write the next brief, ask for both. Ask for the change, and ask for a short note at the end that says what was done, what was skipped on purpose, what's uncertain, and what to check next. Put that ask in the same place every time. The next person to open the work, whether that's a teammate, a fresh session, or you tomorrow morning, will start from what the agent knew instead of guessing at it from the code.

Written by the team building Gander, live review for markdown an agent is still writing.