What a handoff packet carries that a status report does not
RolesAgent Systems EngineeringCustomer AI DeploymentDeveloper Experience and Education
The question
At the end of each session your agent writes a paragraph that says what it did. The next session still spends its first half hour finding out where things stand. What is missing from the end-of-session artifact, and how do you produce it so that it is never skipped?
Answer it first, aloud or on paper. Then open the answer.
The answer
Show short answer
The paragraph is a status report, and a handoff needs seven fields: a summary, the changed files, the commands run, the failed attempts, the open risks, the next action and a pointer to the verification and review reports. The next action is the most important field, because it makes the first step of the next session deterministic. Generate the packet from the workbench artifacts instead of asking the agent to write it, and run a cleanup check first so that the packet describes a tree the next session can trust.
Show full answer
The seven fields
| Field | Question it answers |
|---|---|
summary | What was done, in one paragraph |
changed_files | The diff at a glance |
commands_run | What was executed, from the feedback records |
failed_attempts | What was tried and why it did not work |
open_risks | What can hurt the next session, with a severity |
next_action | The first concrete step the next session takes |
verdict_pointer | The path to the verification and review reports |
A packet with every field except next_action is a status report. It is useful, but the next session still has to decide what to do first.
Generated, not written
A hand-written handoff is the thing that gets skipped on a hard day. The generator reads the state file, the verification report, the review report and the feedback log, and emits the packet in two forms. handoff.md is for the human. handoff.json is for the next agent. If they disagree, the JSON wins. The agent's job is to leave the workbench in a state the generator can summarize.
Trim the log
The feedback log can hold hundreds of records. The packet carries only the last K plus every record with a non-zero exit. The next session loads the full log if it needs it.
Leave a clean state
A perfect packet is useless if the next session opens on a half-applied diff, a stray temp file, a wrong branch and tests that error before they run. Cleanup is its own phase, and it is a check, not a habit. The working tree is committed or stashed with a note. No temp artifacts remain. Tests are green, or red with the failure named in the open risks. The feature board matches reality. The branch is the expected one. The cleanup phase emits a list of blocking issues, and an empty list is the precondition the generator asserts before it writes.
Follow-ups
L1ScreenWhy does the JSON win when the two forms disagree?
Show expected answer
the next agent loads the JSON, so the machine-readable form is the one that drives the next session.
L2WorkingWhich failed attempts belong in the packet?
Show expected answer
every record with a non-zero exit, with the retry chain visible, so that the next session does not repeat a known dead end.
L2WorkingWhat is the difference between a handoff and the state file?
Show expected answer
the state file is read on every turn and holds where the agent is, while the handoff is generated once at session end and tells the next session where to start.
L3SeniorTwo sessions on two branches each wrote a handoff. How does the next session pick one?
Show expected answer
each packet carries a branch, a last known good commit and a status of active, superseded or archived, and only the active packet for this branch drives the session.
Wrong answers
Show the wrong answers that interviewers hear
“Ask the agent to write a detailed summary at the end.”
A written summary is skipped when the session ends badly, and it is the bad sessions that need the handoff most.
“The chat history is the handoff.”
The history is trimmed or gone, and the next session cannot replay an hour of chat in its first minute.
“A green verification report is enough to resume.”
The report proves the task state, not the tree state, and a dirty tree costs the next session its first ten minutes.
Taught in
The multi-session handoff lesson builds the packet out of the workbench files and adds the cleanup check.