session-handoff

session-handoff

A handoff is a document the next session reads to resume work without re-deriving everything from scratch. It is written for a reader with zero prior context — no memory of the conversation, no idea what was tried and rejected, no implicit knowledge of why the current state looks the way it does.

The failure mode this skill prevents: a session ends (context exhausted, or stopped mid-task), the next session opens, and the first twenty minutes are spent reconstructing what the previous session already knew.

Use this skill when

• The session's context window is filling up and the task is not finished.
• A task is being stopped mid-flight and someone (or a future session) will pick it up later.
• Someone explicitly asks for a handoff, a "save state", or a "pick up where we left off" note.

Handoff vs. wrap-up

These are different documents — do not conflate them.

	Handoff	Wrap-up
Purpose	Resume unfinished work	Record finished work
Audience	The next working session	The project record / your future self
Trigger	Context pressure, mid-task stop	Task complete
Includes commits/pushes?	No — work is still in progress	Yes — that is the point
Lifespan	Discarded once the work resumes	Permanent

If the work is done, you want a wrap-up (commit, changelog entry, close the issue). If the work is not done, you want a handoff. This skill is about the handoff.

What to capture

A good handoff has exactly five things. More than this is noise; less than this forces re-derivation.

1. State — one or two sentences: what was being done, and how far along it is. The orientation line.
2. Decisions — every non-obvious choice made and the reason for it. Without the reason, the next session cannot tell a deliberate decision from an accident, and will "fix" things that were intentional.
3. In-progress work — what was mid-change when the session stopped, and the exact resume point: the file and line, the half-applied edit, the command that was about to run. "Continue the refactor" is not a resume point. "src/auth/session.ts:80 — validateToken is extracted but its three callers still call the old inline version" is.
4. Next steps — the remaining work, ordered by priority, each one a concrete actionable instruction — not a topic.
5. Critical context — the things that, if the next session does not know them, will cause a wrong turn: a constraint discovered the hard way, a gotcha, a dead end already explored, an explicit instruction from the user that must be respected. Only things that change behaviour. If it would not change what the next session does, leave it out.