session-handover

name	session-handover
description	Preserve cognitive state before the worker is terminated. Writes only information that cannot be recovered from git. The next iteration of this worker reads the handover to pick up where you left off.

Session Handover

You are about to be terminated by the nancy sidecar (context limit reached or breakpoint detected). Your job is to preserve the cognitive state that would otherwise be lost — the thinking in your head that isn't in the code or git history.

Prime directive

Do not duplicate git. Files changed, diffs, commit messages, file status, branch state — all recoverable. Writing about them wastes tokens and gives the next iteration nothing it couldn't get from git log and git status.

Write only what disappears when you die.

What to write about

Before you start writing, pause and reflect. Ask yourself:

• What mental model did I build this iteration that isn't captured anywhere?
• What "aha" moments did I have that took time to reach?
• What approaches did I try and rule out, and why?
• What did the code teach me that isn't obvious from reading it?
• What was I about to do next, in the next 2 minutes, right before I was interrupted?
• What would trip up a fresh worker starting from this exact state?

The next worker is a fresh Claude with no memory of your session. Write for them.

Steps

Step 1 — Reflect

Spend real thought on the questions above before writing anything. The value of this handover is proportional to the depth of reflection. A rushed handover is worse than none.

Step 2 — Write the handover file

Write to ${NANCY_CURRENT_TASK_DIR}/handovers/${NANCY_SESSION_ID}.md.

Create the handovers/ directory if it does not exist.

Use this structure:

---
task: <task name, parsed from NANCY_SESSION_ID>
session: ${NANCY_SESSION_ID}
date: <ISO 8601 timestamp>
head_sha: <output of `git rev-parse HEAD`>
---

## Where my head was

<The mental model I had built of the problem. The understanding that took
time to develop. The insights about how the pieces fit together that
aren't written down anywhere in the code.>

## What I was about to do next

<The single concrete next action in my head right now. Not a plan — the
actual next move I would have made in the next 2 minutes if I hadn't
been interrupted. Be specific: file, function, what change.>

## Approaches I ruled out (and why)

<Rejected paths. Save the next worker from re-exploring them.>

- Tried <X> via <approach A>: doesn't work because <specific reason>
- Considered <B>: would touch <files> unnecessarily / breaks <constraint>

## Gotchas I learned the hard way

<Non-obvious things the code doesn't tell you. Things that would take the
next worker real time to rediscover.>

- `<file>` looks like <X> but is actually <Y>
- The <framework/library> version here behaves differently on <edge case>
- <Test/fixture> is not what it appears — <real behavior>

## Warnings for next iteration

<Dead ends, complexity traps, files that look simple but aren't. Anything
that would cost the next worker real time if they walked into it blind.>

Step 3 — Update the canonical pointer

Copy the handover to ${NANCY_CURRENT_TASK_DIR}/HANDOVER.md (overwriting any previous version). This is the well-known path the next iteration's prompt template reads.

cp "${NANCY_CURRENT_TASK_DIR}/handovers/${NANCY_SESSION_ID}.md" "${NANCY_CURRENT_TASK_DIR}/HANDOVER.md"

Step 4 — Confirm

Report the path of the handover file. That's all.

Anti-patterns

Do not write:

• "I created src/foo.ts" — git log has this
• "I modified bar() to handle null" — git diff has this
• "I ran the tests and they pass" — the next worker can run them
• Generic status like "Task is 60% complete" — meaningless without cognitive context
• Lists of files changed — git status has this
• Copies of diffs — git diff has this

Do write:

• "I tried refactoring auth.ts first but the session state cascades into middleware.ts — the trick is to extract the session type first, then both can import it"
• "The test file auth.test.ts looks like it mocks the DB but actually hits a real in-memory instance — don't waste time on the mock path"
• "I was about to wire the new SessionStore interface into routes.ts line ~140 — the old getUserSession call needs to become sessionStore.get(req.userId)"
• "src/utils/time.ts looks like a pure utility but parseDate is monkey-patched by the test setup — assume it lies"

Rules of thumb

• If your bullet could be generated by reading git log -p, delete it.
• If your bullet starts with "I did X", ask whether the next worker needs to know WHY or HOW, not WHAT.
• If you're listing things, ask whether the list is useful without context — and if not, write the context instead.
• Brevity over completeness. One specific gotcha beats ten generic observations.