The handoff file
It is a plain markdown file called handoff.md that sits in the folder you are working in. Six headings. That is the whole thing. You write it at the end of a session, then you start a brand new session and tell it to read the file.
Nothing here is Claude-specific. It is a text file — Codex reads it, Cursor reads it, so does the version of you that opens the laptop on Thursday having completely forgotten Tuesday.
Why a file and not a command
A conversation gets summarised. A file gets re-read. That is the entire trick, and it is not a workaround — it is how the tool is built. Section 4 has Anthropic's own wording on it.
The blank file
Copy this into a file called handoff.md if you want to fill it in yourself. Most of the time you will not — you will use prompt 1 below and let Claude do it. But it helps to see the shape first.
# Handoff — [what this job is] — [date] ## 1. Goal What we are actually trying to achieve. The end state, not a diary of today. ## 2. Current state What works right now and what does not, as of this minute. Name the last thing that ran and say whether it passed. ## 3. Active files path/to/file what it is for, in a few words path/to/other/file what it is for (Only the files the next session has to open. Not the whole project.) ## 4. Changes made - What changed, and WHY. The next session can read the diff. It cannot read your reasoning. ## 5. Failed attempts — do not repeat - The thing we tried, and the exact reason it did not work. - Anything that looked right and was not. - Any assumption we made early that turned out to be wrong. ## 6. Next steps 1. The first concrete action, specific enough to start without asking me. 2. The second. 3. The third.
The three prompts
Prompt 1 goes at the end of a session. Prompt 2 goes at the start of the next one. Prompt 3 is for the specific moment where you are going round in circles and need to break out of it.
Before I end this session, write me a handoff file so the next session can pick this up cold. Save it as handoff.md in the root of the folder we are working in. If one is already there, overwrite it — I only ever want the current one. Use exactly these six headings, in this order: ## 1. Goal What we are actually trying to achieve. Not what we did today — the end state. One short paragraph. ## 2. Current state What is working right now and what is not, as of this minute. Be specific about the last thing that ran and whether it passed. ## 3. Active files The files that matter, one per line, with a few words on what each one is for. Only the ones the next session needs to open. Do not list the whole project. ## 4. Changes made What we changed this session and why. The why matters more than the what — the next session can read the diff, it cannot read your reasoning. ## 5. Failed attempts — do not repeat Every approach we tried that did not work, and the reason it did not work. This is the most important section, so be thorough and be blunt. Include the things that looked correct but were not, and any assumption we made early that turned out to be wrong. ## 6. Next steps A numbered list of the specific next actions, in order. Each one concrete enough that someone could start on it without asking me a question. Rules for how you write it: - Write it for a version of you that has never seen this conversation. No "as discussed", no "the file we talked about", no pronouns without a name attached. - Facts only. If you are not sure about something, write that you are not sure rather than guessing. - Keep it to roughly one page. If it is longer, you are including things that do not matter. - Do not put any passwords, API keys or client details in it. If something sensitive matters, write "see my notes" instead. When you are done, print the file back to me so I can read it before I clear.
Then, and only then, clear
Read what it wrote before you clear. It takes twenty seconds and it is the only quality check in the whole system. If the "failed attempts" section is thin, say "you have missed things — go back through the session and list everything that did not work" and make it try again.
Then run /clear. You can name it on the way out — /clear reel batch — and the old session shows up under that name in /resume if you ever want it back.
Read handoff.md in this folder and work from it. Before you touch anything, tell me in your own words: 1. what we are trying to achieve 2. where we got to 3. what has already been tried and failed 4. what you are about to do first Do not start changing files until I have confirmed you have it right. If anything in the handoff contradicts what you can actually see in the files, say so and go with the files. The files are the truth. The handoff is a note someone left you.
The read-back is not politeness. If it has misunderstood the handoff you find out in ten seconds instead of forty minutes and three wrong files.
I am in a loop with you. We have gone round the same problem more than twice and we are not getting anywhere. Stop trying to fix it. Instead, write me a handoff.md in this folder with these six headings: Goal, Current state, Active files, Changes made, Failed attempts — do not repeat, Next steps. Put real effort into "Failed attempts". List every single thing we have tried in this session and the actual reason it failed, including the ones you were confident about. If you now think an assumption we made early was wrong, say which one and say why you think that. Then in "Next steps", give me two genuinely different approaches we have NOT tried yet — not variations on what we have been doing.
What actually goes in each of the six
The headings are easy. Getting them useful is the bit people skip, so here is what each one is really for — and the way each one goes wrong.
Goal — the end state, not the diary
"Cut seven takes into publish-ready reels" is a goal. "Worked on the reels" is a diary entry. If the next session cannot tell whether it has finished, the goal is written wrong.
Current state — as of this minute
What works, what does not, and the last thing that ran. Name it. "Tests pass" is worth nothing next Tuesday; "the linter passes on all 7 plans, nothing rendered yet" is worth a lot.
Active files — five-ish, not fifty
Only the files the next session has to open, each with a few words on what it is. A full file listing is not a handoff, it is a directory, and it buries the four that matter.
Changes made — the why, not the what
The next session can read the diff. What it cannot read is why you cut that section, or why the number changed. Reasoning is the only thing here that is genuinely unrecoverable.
Failed attempts — the whole reason this works
This is the section that saves you an hour, and it is the one that comes out thin unless you push. Without it the new session walks straight back into the wall you spent all afternoon finding — confidently, because it has no idea it has been there. Make it write the reason each thing failed, not just that it did.
Next steps — numbered and startable
Each one specific enough that work can begin without a single clarifying question. "Fix the crop" is not a next step. "Crop the channel screenshot above the Customise-channel buttons" is.
The one that gets skipped is the one that matters
If you only ever write one section properly, write failed attempts. Goal and next steps you can reconstruct in your head. The list of things that look fine and do not work is the expensive knowledge, and it is the first thing a summary throws away.
A real one, filled in
This is an actual handoff from a job I ran on 08/09/2026 — cutting a batch of filmed takes into reels. I have taken the file paths down to something readable and pulled out anything private, but the shape and the content are real, including the bit where I admit I gave up on a website after two attempts.
# Handoff — reel batch 08/09/2026 ## 1. Goal Cut seven filmed takes into publish-ready vertical reels. Original spoken hooks on screen, b-roll pinned to the word, every on-screen number verified at source. ## 2. Current state All 7 beat plans pass the linter. 21 browser captures inspected. Rough cut done on HANDOFF only (131.9s -> 76.4s). No reel rendered yet. ## 3. Active files plan/<slug>/beats.json the locked plan, one per reel assets/raw/<slug>.words.json word-level timings assets/captures/<slug>/ screen recordings tools/cut_handoff.py the silence cutter BROLL-MANIFEST.md where each clip came from ## 4. Changes made - Hooks locked to my originals, emoji rotated on two axes - HQ: cut 62.10-68.58, the contested token-limit claim - WEDGIE: retitled 8 -> 7 channels, tally rebuilt to 7 rows - BOOGIE: reworked to big logo drops, all 5 logos verified at source ## 5. Failed attempts — do not repeat - Finding the silences from the word timings. The transcriber stretches a word's end across the pause after it, so it missed 12 of the 23 real pauses. Measure the actual audio level instead. - ffmpeg silencedetect on the source file. Returns nothing at any threshold. - 21st.dev at phone width: served a single component page, would not scroll. - 21st.dev at desktop width: right page, still would not scroll. Stopped after two methods and used a static capture instead. - faster_whisper is not in the main python. It lives in its own venv. ## 6. Next steps 1. Crop the channel screenshot above the Customise-channel buttons 2. Record the Claude Code beats: context meter, /compact, /clear, real typing 3. Validate the 7 CTA keywords before any CTA card gets built 4. Render, then check: sync, loudness, mobile-safe placement
Look at what section 5 is doing
Six lines, and every one of them is an hour I do not have to spend again. Two of them are "this tool behaves differently to how you would assume". One is "I tried twice and stopped" — which reads as an admission and is actually an instruction: don't you start either.
That is the whole value of a handoff, and it is exactly the kind of detail a summary flattens into "encountered some issues with the captures".
Why /compact does not fix it
Fair warning: I said on camera that compact does nothing. That is not quite right and I would rather correct it here than let you find out yourself. Compact does exactly what it says — it frees up room. What it does not do is give the model a clean head, and those are two different problems that feel like one.
Here is Anthropic's own description of what happens when a session compacts, from the Claude Code docs (read 08/09/2026):
"Claude Code manages context automatically as you approach the limit. It clears older tool outputs first, then summarizes the conversation if needed. Your requests and key code snippets are preserved; detailed instructions from early in the conversation may be lost."
Read that second sentence again. It summarises the conversation — all of it. Every wrong turn you took at 2pm is in that summary. And the thing it drops is your careful early instructions.
So compacting is lossy in the least helpful direction available. You keep a blurry version of the mess and lose the sharp version of the brief. That is context rut, and it is why hour four feels worse than hour one even though nothing has technically gone wrong.
Meanwhile, here is what a brand new session looks like — same docs:
🔄 /compact
- "Free up context by summarizing the conversation so far"
- The dead ends come with it, in summary form
- Your early instructions are the bit at risk
- Costs tokens — it has to read everything to summarise it
- Right choice when you need continuity
✨ /clear + a handoff file
- "Start a new conversation with empty context"
- Nothing comes with it except what you wrote down
- Your brief is the file, so it cannot get summarised away
- Costs nothing
- Right choice when you need a clean head
And the reason the file survives when a conversation does not is written into how compaction works. Anthropic publish a table of what happens to each kind of content, and the pattern in it is the whole game: things loaded from a file get re-injected from disk. Things that live in the conversation get summarised.
Their own words, from the same docs
On starting fresh: "Sessions are independent. Each new session starts with a fresh context window, without the conversation history from previous sessions."
On when to use which: "Clear between tasks: Use /clear to start fresh when switching to unrelated work. Stale context wastes tokens on every subsequent message."
And on the cost: "/compact reads the conversation it summarizes, so compacting a large context is itself a large request. When you want a fresh start instead of continuity, /clear costs nothing."
None of which makes compact bad. It is the right tool when you are halfway through one continuous piece of work and simply need room. It is the wrong tool when the problem is not room — it is that the session has picked up four wrong ideas and is building on all of them.
When to run it — and where it does not help
Before you walk away for hours
School pickup, a call, tomorrow morning. Write the handoff while you still remember why you did things, not when you come back and do not.
The third time round the same problem
Two attempts is debugging. Three is a loop, and the loop is being fed by the context. Prompt 3 above is built for exactly this moment.
When the answers start going vague
Hedging, re-explaining things you settled an hour ago, suggesting a file you already deleted. That is the tell. Handoff and clear.
Switching to a completely different job
Finished the invoices, starting on the website. Nothing from the first job helps the second one, and all of it is still being sent with every message.
Before anything you might want to undo
A big rename, a restructure, anything touching a lot of files. If it goes badly you have a written record of the state it was in beforehand.
When you hand the job to someone else
Same file works on a human. A VA, a contractor, or you in a month. It was never really about the AI.
Three honest limits
1. Writing it costs a bit of context. Do it when you have room, not at the very end when you are scraping the bottom. If Claude is already struggling, ask for the handoff first and the last little fix second.
2. The handoff is a note, not the truth. The files are the truth. That is why prompt 2 tells it to go with the files if the two disagree — a handoff written an hour ago can be out of date, especially if you kept working after you wrote it.
3. Watch what ends up in it. If your folder is a git repo, handoff.md will get committed with everything else. Prompt 1 tells Claude to keep credentials and client details out of it, but have a read before you commit — and add it to .gitignore if you would rather it never went anywhere.
The version that takes ten seconds
If you take nothing else from this page: write down what did not work before you clear. Not the goal, not the file list — the failures. Everything else you can rebuild in your head. That list you cannot, and it is the most expensive thing in the session.
Ready to go deeper?
The handoff file is the easy half. The useful half is knowing what to point Claude at in the first place.
Wright Mode Membership
Join a community of women using AI to take real work off their plate. Live calls, copy-paste prompts and workflows, and ongoing support.
Claude Masterclass
Learn to use Claude like a pro — from prompting fundamentals to building real workflows that save hours every week.
Claude Code Masterclass
Go beyond the chat box. Build automations, process data and create tools with Claude Code — no developer experience needed.