Write the handoff before clearing the agent context

Before I end an agent session, I write down where the work actually stands and the command that should run next. Otherwise the next session has to piece it all back together and might redo changes that are already done. The transcript feels like a record, but it's a bad place to restart from. It's full of abandoned ideas, tool output, corrections and old versions of the plan, and even if the next agent searches it, it burns context and still can't be sure which parts are current.

So I write the handoff after checking the workspace itself, because the agent's final summary can be wrong if a command failed or a file got edited again. For code, that means the branch, the working tree and the relevant diff, including changes that were already there and any untracked files the next session needs to leave alone. For data or ops work, the state might live outside Git entirely: a job ID, an output path, the last accepted batch, a pending approval. I name the system it lives in and use identifiers rather than copying credentials, customer data or message contents into the note. If I can't verify something, I say so. "Deployment started" and "deployment completed and the health check passed" are very different claims.

Then I sort the work by status:

• done and checked
• changed but not checked
• tried and failed
• still to do

A transcript might show tests passing and then the code changing afterwards, so "tests passed" on its own is misleading unless you say whether they ran against the current files. For failures, I keep the command, the error and whatever diagnosis the evidence supports, plus a path to a saved log. If I've only got a hunch about the cause, I label it as a lead and say what would confirm it.

I also write down the decisions that still constrain the work, like scope, files someone else owns, areas to leave alone, or an external write that still needs approval. I keep these near the task (repository instructions, an issue, a handoff file) rather than trusting agent memory, and I link to a longer spec instead of paraphrasing it.

"Continue the work" leaves the next session guessing, so I leave the exact next command, the directory to run it in, what a good result looks like and whether it changes anything outside the local machine, or, if the next step is really a question for a person, the question and the evidence. Then I save the note where the next session will look, with a timestamp or commit reference, and check that the files and commands it mentions exist. That's why the handoff gets written before I clear the agent context: the next session should start from a checked note of what's done, what isn't and what to run, instead of piecing it back together from the transcript and redoing changes that are already finished. My last check is whether someone could run the next safe step from that note without opening the transcript at all.