The Session Handoff

Every AI session starts fresh. The handoff file is the baton you pass to your future self — a structured document that lets the next session pick up exactly where you left off, without a single minute of re-explanation.

The Problem With "Starting Fresh"

In Part 2 we built four memory files that hold everything the AI needs to know about your world: current state, settled decisions, hard-won lessons, and running context. Those files solve the knowledge problem. But there is a second, more immediate problem that happens at the end of every working session.

You have been deep in a task for two hours. Three things are half-done. One is blocked waiting on you. Another succeeded but you have not yet updated the state file. You close the laptop. Tomorrow, when you open a new session, all of that working context — which task is in flight, what the last known good state was, what you were about to do next — is gone from the AI's perspective. Not from your memory files, but from the situational layer: what just happened, what still needs to happen, and in what order.

This is where the handoff file comes in. It is not a general knowledge base — that is what your memory files are for. The handoff file is a point-in-time snapshot of work in progress, written at the end of one session so the next session can resume without any setup conversation.

What Goes in a Handoff File

After trying several formats, we settled on five sections. Each one answers a specific question the next session will need answered in the first sixty seconds.

1. What was completed this session

A short, specific list of things that are done and verified. Not "worked on the content pipeline" — that is useless. Instead: "Generated and QA-gated eighteen pages for the educational hub; all eighteen are live and returning correct responses through the public URL." The specificity matters because it prevents the next session from accidentally duplicating work that is already done.

2. What is in flight (and its exact state)

This is the most important section and the one most often skipped when you are tired at the end of a session. For each unfinished task, you need: what the task is, what step it is currently on, what the last known good state is, and what the very next action would be if you were to resume right now. The next session should be able to read this and begin working within one minute — no detective work required.

3. What is blocked and why

If something cannot proceed without a decision or an external dependency, say so explicitly. "Blocked: the new content batch cannot be scheduled until the operator confirms the target publish date." Blocked tasks have a specific anatomy: what is blocked, what it is waiting for, and who needs to act. If that is not written down, the next session either ignores the blocker and wastes effort, or asks you to re-explain it from scratch.

4. Priorities for the next session, in order

This is the handoff's most actionable section. Write it as a numbered list. The next session should be able to read item one and start working on it immediately. Do not make the AI decide what to work on — it will make a reasonable guess, but your judgment about sequencing is better than its guess.

5. Critical warnings

Anything the next session must not do, or must be careful about. "Do not regenerate the sitemap until the operator approves the URL structure — this requires sign-off per our operating rules." Or: "The staging environment is currently misconfigured; test through the live URL only." Warnings are the cheapest possible insurance against repeating a mistake you just spent two hours recovering from.

A Worked Example

Here is what an actual handoff looks like — abbreviated, but structurally complete. Notice that it is not a diary. Every line is either an action taken, a state, or a next step.

# SESSION HANDOFF — 2026-06-04

## Completed this session
- Educational hub: 18 pages generated, QA-gated, deployed, verified live
- Sitemap updated to include new hub pages; submitted to GSC
- Backlink outreach template drafted (not sent — see blocked section)

## In flight
### Ad configuration audit
- Status: step 3 of 5 complete
- Last good state: checked the first two site zones; both clean
- Next action: run the same check against the remaining three zones
  (script: tools/ad-audit.sh — use flags --zone 3 --zone 4 --zone 5)

### Content batch for the games vertical
- Status: template designed, not yet generated
- Last good state: prompt template saved at drafts/games-batch-prompt.md
- Next action: run the generation job with --batch-size 10 (NOT the
  full batch — we hit a rate limit last time running it all at once)

## Blocked
- Backlink outreach emails: waiting for operator to confirm the
  sending domain. Cannot proceed until confirmed.

## Priorities for next session (in order)
1. Complete the ad audit (zones 3-5) — estimated 20 minutes
2. Run games content batch (size 10, then QA-gate before more)
3. Resume outreach once operator confirms sending domain

## Critical warnings
- Do NOT run the full games batch in one job — last time this
  triggered a shared rate limit and most work came back empty.
  Batches of 10, then pause and check before continuing.
- The staging subdomain is currently returning stale cached responses.
  Verify all deploys through the live public URL only.

A session that opens this file knows exactly what to do. It does not need to ask what was worked on. It does not need to discover that the batch job has a size limit the hard way. It picks up item one on the priority list and starts.

When to Write It

The handoff is most useful when written during the session, updated as each task completes, rather than reconstructed from memory at the very end. The end-of-session reconstruction is the most common failure mode: you are tired, you skip the in-flight section because "you will remember," and the next session opens to a handoff that says "completed: worked on stuff" and "next: continue."

The practical discipline we landed on: update the "completed" section as each task finishes, and update the "in-flight" section whenever you move from one task to another. The end-of-session pass then takes three minutes rather than fifteen, because you are filling in priorities and warnings, not reconstructing the whole session from scratch.

How the Next Session Uses It

At the start of every session, the AI reads the handoff file as part of its startup sequence — alongside the state and decisions files from Part 2. The order matters: state and decisions first (to rebuild the general picture of the world), then the handoff (to understand what is specifically in progress and what to do next).

Once it has read the handoff, the session should require no orientation conversation. You should be able to open a new chat and type "resume" — or nothing at all if the startup sequence is automated — and the agent picks up item one on the priority list and starts working.

This is what turns an AI from a tool you have to brief every time into something closer to a colleague who was simply away for the night. The colleague does not need you to re-explain the project. They read their notes and they get back to work.

The Handoff and Your Other Memory Files

One question that comes up: is the handoff file the same as the state file? No, and the distinction is worth holding clearly.

• The state file describes what is true about your system right now — what sites are live, what decisions are in force, what the current architecture looks like. It is updated infrequently, when durable facts change.
• The handoff file describes what is true about your work in progress right now — tasks half done, blockers in place, the next action queued up. It is updated at every session boundary, sometimes mid-session.

The state file is a reference you consult. The handoff file is a baton you pass. They serve different purposes and should stay separate — conflating them creates a file that is too long to scan quickly and too volatile to trust as a stable reference.

Similarly, when a lesson emerges from a session — something general that will apply again and again — it moves out of the handoff and into the lessons file. The handoff entry might read "rate limit hit on full batch job — see lessons file for the rule." The detail lives in lessons; the pointer lives in the handoff. This keeps both files at the right level of specificity.

The One Rule That Makes Handoffs Work

Every other piece of advice in this article depends on a single underlying commitment: the handoff file must be written before the session ends, not as an afterthought. The most dangerous moment is when you feel like you are "almost done" and just need to do one more quick thing. That one more thing expands, the session ends, and the handoff never gets written.

Set a personal rule: no session ends without a handoff update. Even if it is five lines. Even if all it says is "completed nothing today, the thing I was trying to do is blocked because of X, unblock it by doing Y." That is still a useful handoff — it tells the next session not to spin its wheels trying to make progress on something that is not moveable yet.

The habit compounds. After two weeks of consistent handoffs, you will notice something: you spend almost no time at the start of sessions figuring out where you are. You just read the file and go. That recovered time — across every session, indefinitely — is the return on a five-minute investment made at the end of each day.

Your action for today: open a text file called SESSION-HANDOFF.md in your project directory. Write down what you are currently working on, what state it is in, and what the next action would be if you had to hand it to someone else right now. That file, kept current, is worth more than any other single investment you can make in your AI workflow.