A practical handoff template for file paths, verification status, access locations, and the next action.
An AI session had already used an API key for a task. Later, in a new session, I asked it to continue with the same access.
It did not know where the key was stored.
I went back to the old conversation, asked for the location, and brought that information to the new one. The missing detail was tiny compared with everything we had discussed. Recovering it still interrupted the work.
After more than a year of working intensively with AI across many sessions, I had collected plenty of these interruptions. A new session could understand the feature we were building and still lack something it needed to continue.
I started paying closer attention to what a task handoff should preserve.
What I wanted to carry into the next session
Sometimes I wanted to continue an unfinished task in a fresh context. Sometimes I wanted to switch from Codex to Claude Code, or use a different model for the next stage.
The old conversation could contain useful decisions alongside failed attempts, lengthy logs, and ideas we had decided against. Copying it all forward would bring that accumulated material into the new session too.
I wanted enough information to continue correctly, with references to anything the next agent might need to inspect.
A fresh session still has reading to do. It may need to inspect files and test results before acting. A handoff gives that reading a starting point; it does not transfer the old conversation’s entire memory or guarantee lower token usage.
Describe the state of the task
“We are adding a settings panel” describes the subject. It leaves a lot unanswered.
Which setting? What did I approve? Which files changed? Was the change built? Did anyone launch the application? What was the agent about to do when I stopped it?
Those details affect the next action. If the new session assumes a proposed change was approved, it can continue in the wrong direction. If it mistakes an edit for a verified fix, I may think the task is further along than it is.
The question I would ask of a handoff is: can the next session read it and identify the first thing to check?
A reusable handoff template
This is a starting point, not an export from a private project. Ask the outgoing session to fill it with actual paths and observations, and explicitly mark anything it cannot establish as unknown.
# Task handoff Updated: Project and working directory: Branch or revision: ## Requested outcome What the user asked for and the acceptance conditions. ## Current state - Completed: - In progress: - Blocked or unresolved: ## Relevant files Exact paths and a short reason each file matters. ## Changes already made Edits for this task and unrelated local changes to preserve. ## Verification - Checks actually performed: - Results and evidence locations: - Checks not performed, and why: ## Decisions and boundaries Approved decisions, rejected approaches, and task limits. ## Environment and access Required tools, services, URLs, and configuration locations. Record how approved access is obtained, not secret values. ## Next action The first concrete step, followed by remaining work. ## Open questions Questions still needing an answer, separate from approved decisions. A small task may need only a few lines under these headings. A difficult debugging task may need references to a diff, logs, and earlier evidence.
The note should point to larger records when those records remain accessible. There is usually no reason to paste an entire log into the handoff if the next session can inspect the relevant file.
Keep “edited” separate from “verified”
Suppose an agent has changed how a desktop application saves a setting. An illustrative handoff could say:
Requested outcome: The selected option should persist after closing and reopening the app. Current state: Persistence code has been edited. Runtime behavior is unverified. Verification: No successful build or runtime test is being claimed in this example. Next action: Inspect the current diff, identify the repository's build procedure, then build and check the setting across an application restart. In a real note, I would expect the exact component paths and any checks already performed. If a build failed, record the command and where to find the failure. If the agent only read code, say that.
This distinction matters to me because I build desktop software. An interface change can compile and still need testing in the running application.
A handoff that says “done” without explaining what was checked leaves the next session, and me, to guess.
Preserve access information without copying secrets
The API-key incident made me pay more attention to configuration locations, service names, and URLs. They can occupy very little space in a conversation while being necessary for the next step.
For credentials, preserve where approved access is managed and how the destination session should obtain it. Avoid copying the key itself into a handoff, then another prompt, then another summary.
The destination also needs access to the referenced files. A path on my main computer may mean nothing to a session on another machine.
Knowing a path does not establish permission to read its contents. A note identifying a remote laptop does not establish that the new session is connected to it.
These are things to verify before continuing.
Separate standing instructions from unfinished work
A project’s standing instructions explain conventions that apply across tasks. A handoff explains what is happening now.
I would keep temporary debugging state in a dated task note rather than continually appending it to permanent project instructions. Otherwise, yesterday’s unfinished work can remain mixed in with rules intended for future sessions.
For example:
- Project instructions: how to build, coding conventions, and boundaries that apply across tasks.
- Task handoff: the current request, edits made, verification results, blockers, and next action.
Loading project rules helps orient a new agent. It does not, by itself, tell the agent what the previous conversation had just finished doing.
Ask the new session to check its position
A handoff can become stale. Another session may have edited the files after the note was written. A task recorded as unfinished may already be done. The branch or working directory may differ.
I would begin the new conversation with this instruction:
Read the applicable project instructions and the task handoff. Check the current working directory, code state, and referenced evidence. Identify any mismatch with the note before editing. Preserve unrelated changes. Continue with the recorded next action if it still applies. Report checks as passed only when you have actually run them or inspected their recorded results.
This is a suggested prompt, not a claim that I tested every tool’s handoff behavior.
If the note and repository disagree, the new session should report the mismatch and establish the current state before relying on the old plan.
Review the handoff before leaving
Before moving on, I would check four things:
- Can the next session find the relevant files and environment?
- Does the note distinguish completed edits from verified behavior?
- Are unresolved questions separate from approved decisions?
- Is the next action specific enough to begin?
In my own workflow, I implemented a way to prepare and pass the handoff when creating the destination session. That removes manual copying, but the quality of the record still matters.
A manually written Markdown file can use the same structure. The important part is that it accurately records the task and remains available to the next session.
I wrote about the broader experience in My Claude Code and Codex Workflow: The Problems I Had to Solve Myself.
Having to return to an old conversation just to recover a configuration location taught me how easily a small omission can stop the work. That is the kind of detail I now want the handoff to preserve.
Author’s note: I am the founder of AigoPilot. This article was written with AI assistance from my own development experiences. The cover is an AI-generated illustration. The template and example prompts are proposed workflows, not benchmark results or exported private project records.
