# HANDOFF.md starter

Save this in your project and keep it current during any long piece of work.

**Why this file exists.** A long Claude Code session eventually runs out of room
and compacts itself: it summarises the conversation so far and carries on from
the summary. That happens on a size threshold, not at a sensible stopping point,
so it can land in the middle of something. What practitioners report losing is
the specific stuff: error details, exact file names, the middle steps of a long
piece of debugging, and the reasoning behind decisions already made.

This file is the fix, and it is deliberately low-tech. Anything written here is
on disk, so it survives. Anything living only in the conversation does not.

Write it for a stranger. In practice that stranger is Claude in twenty minutes,
with no memory of the last two hours.

---

## Goal

[What we are trying to achieve, in one or two sentences. Not the task list, the
outcome.]

## Where things stand

[What is genuinely finished. Include one hard fact per item that proves it is
finished, for example a count, a filename, or a check that passed. "Mostly done"
is not a status.]

## What is in flight right now

[The thing being worked on this moment, and how far in.]

## Decisions already made, and why

- **[Decision]**: [why, and what the alternative was]

The "why" is the part that gets lost. Without it, the next session relitigates a
question you already settled.

## Open questions

- **[Question]**: [what would resolve it, and who decides]

## Gotchas already hit, do not rediscover

- [What went wrong, what it looked like, and what fixed it.]

This section is worth more than the rest of the file combined. Every entry is
time somebody already spent.

## Next steps, in order

1. [Next concrete action]
2. [The one after that]

---

## How to use it

- Update it before any long run, and after anything surprising.
- After a reset, a new session, or when answers start feeling vague, say:
  **"Read HANDOFF.md and continue from the next step."**
- If you find yourself re-explaining something you already explained today, that
  belongs in here.