Write the handoff before clearing the agent context

Before ending an agent session, I write down the current state and the command that should run next. Without that, the next session has to reconstruct the work and can repeat changes that are already complete. A long transcript feels like a record, but it is a poor restart point. It contains abandoned ideas, tool output, corrections and earlier versions of the plan. The next agent can search it, although that spends context on rediscovery and still leaves uncertainty about which statements remain current. A short handoff should describe the workspace as it exists now. The handoff should be prepared after checking the repository, files and running processes. An agent's final explanation can be wrong if a command failed, a file was edited again or an external operation completed only partly. For code work, I check the current branch, working tree and relevant diff. I record changed files, unrelated changes that were already present, and any generated files or untracked evidence the next session must preserve. A shared or dirty workspace is not a blank one.

For data or operational work, the state may sit outside Git. A job identifier, output path, last accepted batch, deployment status or pending approval can matter more than the conversation. The handoff should name the system of record and include stable identifiers, while keeping credentials and private payloads out of the note. If I cannot verify a state, I write that plainly. "Deployment started" is different from "deployment completed and the health check passed". The second claim requires evidence from the target environment. A useful handoff tells the next session what it can rely on. I divide the work by status in normal language: completed and checked, changed but not checked, attempted and failed, still to do. This prevents a common restart mistake. A transcript may show that an agent ran a test, then later changed the code. Saying "tests passed" without noting the order gives false confidence. The handoff should name the check and whether it ran against the current files. Failures need enough detail to avoid an identical retry: the command, relevant error and any diagnosis already supported by evidence. A path to a saved log is usually more useful than pages of raw output.

Do not turn guesses into settled decisions. If one cause looks likely, label it as a lead and state what would confirm it. This gives the next session somewhere to continue without locking it into an unproven explanation. The next agent needs the decisions that still constrain the work. These might cover scope, accepted behaviour, file ownership, data handling or an explicit instruction to leave an area alone. A decision should include its reason when that reason will help resolve later ambiguity. I keep these notes close to the task rather than relying on agent memory. Repository instructions, an issue or a task-specific handoff file are easier for a fresh session to inspect. The note should link to a longer specification rather than paraphrasing it until the requirement changes. Boundaries matter in shared workspaces. If another person or agent owns a set of files, record that. If unrelated changes must remain untouched, say which ones were observed. If an external write still needs approval, the handoff must not imply that the next session can perform it automatically.

Private information deserves the same discipline. A handoff can refer to a secure record by identifier rather than copying customer data, credentials or message contents into a broadly visible file. "Continue the work" makes the next session decide what continuation means. I leave the exact next command when a command is appropriate, plus the directory it should run in and the expected signal. The command might run a focused test, inspect a diff, resume a batch or open a generated preview. It should match the current state and include the expected signal. For an operation with side effects, I also state whether it is read-only, creates a local artefact or changes an external system. Sometimes the next step is a decision for a person. In that case, the handoff should name the question and the evidence available, then stop. An executable command is useful only when execution is actually authorised.

A handoff is a current index, not a second transcript. Mine usually needs the objective, current state, changes made, checks run, unresolved issue, boundaries and next action. Links and file paths can carry the detail. The note also needs a timestamp or commit reference when the workspace can change independently. To check it, ask whether someone can identify the current files, distinguish verified work from unfinished work and run the next safe check without reading the transcript. Any missing answer belongs in the note. Before ending the session, I save the handoff where the next session is expected to look, then verify that the referenced files and commands exist. Once the current directory, branch or target system, outstanding side effects and next command match the note, clearing the context is a controlled transition rather than an invitation to reconstruct the project from tool history.