How to hand off work between process stages

"Export is fixed, still needs checking" - and that's where the work stopped. The next day you open the project and can't tell which files changed, which version you were on when you looked at the export, or where the check left off.

To continue without investigating everything again, the next stage needs the saved result, what was checked and the immediate next step. Let's walk through a handoff like this using a single task: it could be run by one session, by several people or agents, or by you yourself across two sittings.

Hand off a result that can be opened

CSV export is broken in a shopping list app. The requirement: the export contains only the rows shown on screen and keeps their order. For an empty list, the agreement is to keep the header row, with no data rows. The column format and the delimiter stay as they are.

Instead of "fixed, still needs checking", we'll leave a record that lets someone find the changes and carry on. The hashes and results below are made up: this is a teaching sample, with no real runs behind it.

HANDOFF
Goal: the CSV contains only the rows shown, in their current order.
Input version: base commit 4f1c2ab.
Handed-off state: commit 9d3e740 on branch fix-export, no extra edits.
Result: src/export-csv.js - export takes the list after filtering and sorting.
Checked manually on 9d3e740: source items A, B, C; on screen C, A;
  CSV data rows C, A, no item B. The header doesn't count as an item.
Not checked: empty list; "incomplete only" mode.
Decision: column format and delimiter unchanged.
Next step: the main session checks the two remaining scenarios.
Overall task status: checking not finished.

The letters stand for three items in the list. The scenario checks two properties at once: hidden item B didn't make it into the export, and the order C, A matches the screen. Just getting two rows out of a list that only has two isn't enough (an export with no filtering at all would give you exactly that).

You can save the record in HANDOFF.md or append it to an existing task document. No mandatory set of fields, really. What matters is that the next person or agent can open the record along with the files it refers to, even without access to the earlier conversation.

If a command did the checking, note the command along with its actual result and the code version. "12 of 12 passed" doesn't say what behavior was checked. A manual scenario needs the input data, the action and what you observed, as in the example above.

Set entry and exit conditions

A handoff is useful when the next stage can tell whether the information it got is enough. For our task, that fits into three rows.

The key column here is the rightmost one. at the handoff to verification, it answers the question "can checking start?". Even a fully described fix may still turn out to be wrong. And a finished check may send the bug back for fixing: a useful report doesn't have to announce success.

If no version is given, first establish the current state of the files. You can check that state, but you can't carry an old report over to it without comparing. Stages don't need separate agents or documents, either. A small task can go through all three in one session with a single note.

Preserve the accepted state

In a handoff, it's easy to mix up three different things:

• the saved state of the code - a specific version you can restore;
• a progress note - what was done, what was checked, what was agreed;
• acceptance of the result - the decision that what's been done is enough for the goal.

A commit points to the files saved in it. But if there are extra changes after it, the reference no longer describes the whole state being handed off: those edits need to be saved and listed separately too, new files included. When handing off a set of changes, also give the base version they should be compared against. A branch name on its own won't do, the branch keeps moving.

Picture this: the record says 9d3e740, but the export file has been edited since. The recipient sees a familiar hash but will be working with different code. So the first step is finding out what changed. If the edit touched which rows are selected or their order, the earlier C, A check no longer confirms the current behavior. If only a comment's wording changed, that alone is no reason to rerun the scenario.

You don't have to commit after every step or bundle your own edits and someone else's into one commit. What matters is that the state being handed off exists in full and is accessible to the recipient; how it's saved is up to the project's conventions. If the files aren't in place, check the saved version first. If the changes weren't saved anywhere, well, no note will bring them back.

Resuming a conversation doesn't, by itself, bring the files back to the described version. Claude Code's edit checkpoints don't cover every change either: edits made through Bash aren't tracked, and restoring changes made by other sessions or people has limitations. That's why a handoff relies on saved files and their version. More: Checkpointing.

Figure out why the work stopped

"It didn't work" covers at least three different situations.

A local run was interrupted. A command didn't finish, or a check broke off halfway. First find out what managed to run and what changed. If the cause is fixed and a retry won't duplicate an action that already happened, you can repeat the unfinished step. For our example, let's agree on a single retry; if that one breaks off too, we write down why it stopped and what's needed to continue. The limit depends on the operation. Retrying forever just won't explain anything.

The expected behavior is unclear. For example, whoever is doing the work doesn't know which rows count as shown when a filter is on. First they check the written requirement. If the answer isn't there, they put the question to whoever owns the requirement. The fix can continue once there's an answer; rerunning won't replace it.

A new fact overturned an accepted decision. Turns out another program reads the CSV. Once that was clarified, a different set of columns was agreed on, and the ordering requirement was dropped. The work goes back to clarification: the new criterion needs to be written down, and the fix and checks that depend on it reviewed. A scenario that passed earlier may still be useful, but it no longer confirms the whole updated task.

Here the work goes back to clarification because the original decision changed. If the requirement stayed the same and the bug is in the implementation, going back to the change stage is enough. The results that get revisited are the ones that depend on the affected decision.

Resume from the current point

Picking the work back up comes down to five steps:

1. read the whole handoff, including what wasn't checked;
2. compare the handed-off state with the files you have and any extra changes;
3. find out how an interrupted operation ended, if there was one;
4. decide which earlier results are still valid;
5. do the next unfinished step and update the record.

Back to the original example, where the requirements didn't change. The next session opened the handoff and compared the state: commit 9d3e740 is available, there are no extra edits, and the data and check conditions are the same as before. The C, A scenario is already done, and its result still applies. No need to write the fix again.

Now the recipient checks the empty list. Per the task, the CSV should keep the header row with no data. In our made-up continuation, that's exactly what happened. All the record needs is the new result and an updated remaining step:

Checked manually on 9d3e740: exporting an empty list gives only the header.
The earlier C, A scenario still holds.
Not checked: "incomplete only" mode.
Next step: the main session checks this mode.
Overall task status: checking not finished.

The handoff changed along with the work. One of the two remaining scenarios is done, and the other is still listed. A partial result doesn't close the original goal; moving a check to another task takes a separate decision to change the scope.

If a run broke off, you may need to repeat the interrupted scenario from the start: not every tool can pick it up from the middle. Checks that finished earlier stay valid as long as their code, input data and conditions are still current.

Who prepares the handoff

Claude Code can gather the facts, check the next stage's input and carry out a step that's already been agreed. You check that the record matches the files and the run results. Disputed requirements and scope changes are decided by a person or a designated owner; in our process, final acceptance stays with a person.

A saved version helps you continue the work, but it doesn't give whoever does the work any extra authority. If the job is to check the export, a restore point is no license to change the column format while you're at it. The task's boundaries still apply after the handoff.