Session Handoff Skill

Long sessions fill with superseded plans, aborted scratchpads and repetitive error traces, and instruction adherence, reasoning precision and tool accuracy degrade as the context grows. Starting fresh restores performance, but discarding context blindly causes state loss, invented progress and repeated mistakes. The session-handoff skill standardizes how an agent snapshots its active state and turns ephemeral working memory into an actionable, verifiable bridge document for the next session.

It follows a six-step sequence when a session reaches its limits or work halts:

1. Audit git and workspace state with git status -s and git diff --stat, never trusting chat memory for what changed.
2. Capture the goal in one sentence, then what is verified working, with passing commands, versus partial or unverified.
3. Record decisions made and discarded paths, including approaches tried and rejected, so they are not retried.
4. Catalog files touched and relevant symbols, with line references where useful.
5. Isolate open loops, each with an owner (Human or Agent) and a way to verify completion.
6. Specify one atomic next action: the exact command to run or file to edit first.

Use it when context usage approaches capacity (roughly above 60%) and a reset is coming, before clearing or compacting a session, when switching tasks mid-session, or when ending a session that another session or agent will continue.

It is not a substitute for other tools. It produces a written handoff only and cannot preserve live state such as running processes, uncommitted terminal output or in-memory debugging context, so anything that matters must be written into the note. The note is only as good as what the outgoing session records. It does not replace version control or issue tracking: commit work first and reference commits or tickets instead of duplicating them.

The input is the live workspace and the session itself: git status and diff output, test results, the decisions taken and the files touched. The output is a markdown note with sections for goal and current state, decisions with reasons, files changed, open loops, next action and watch-outs. The source includes a worked example for a refresh-token rotation task in an auth service, where the note lists the verification command that passes, why one storage option was chosen and another rejected, the exact functions and files changed, open loops tagged to an owner with a deterministic check, and a first instruction naming the file to open.

Four operating rules shape the content. Separate facts from speculation, and label untested assumptions as [UNVERIFIED]. Give every open loop an owner and a deterministic verification criterion. Ban vague continuations such as "continue working on auth"; state the exact symbol, file and failure mode. Reference real file paths and symbol names rather than pseudocode.

The skill relies on git commands for grounding and applies in any coding tool that has a clear or compact step for resetting a session. It pairs with version control and issue tracking rather than replacing them.

Developers and agent operators who run long coding sessions and need the next session to start with correct, checked state. It also helps teams where one agent hands work to another. The anti-patterns it names are worth knowing: dumping the raw chat transcript, marking a module completed when it was only written and never run, omitting dead ends so the next session repeats them, and ending on an abstract next step that costs several turns of rediscovery.