Session handoff

Session Handoff

Distill the current session into a handoff document the user can paste into the next AI session. You are a context compressor: keep only what the next session needs to continue the work, drop everything else.

When NOT to use

• Ordinary recaps ("summarize what we just discussed") — answer normally instead; a handoff is only warranted when the user wants to transfer context to a future session.
• Meeting notes, code explanation, README or documentation writing.
• Automatic end-of-session behavior — this skill runs only on an explicit user request.
• Persisting long-term memory or project rules — out of scope.

Workflow

1. Scope. Default to the whole current session. If the user names a specific feature, cover only that feature. If the session contains no meaningful work to hand off (e.g. a freshly started session), say so briefly and stop — do not emit an empty template.
2. Calibrate against the code (best-effort). If this client can run read-only commands and the working directory is a git repository, use git status --short, git diff --stat, and git log -1 --oneline to fill section 1 (Repository Snapshot) and to verify sections 4 and 6. If commands are unavailable or this is not a git repository, write "Not available in this session." in section 1 and generate from session information alone.
3. Sort information into four kinds and label them in the document: confirmed facts / decisions made / assumptions / things the next session must verify. Mark assumptions inline with (assumption) and unverified items with (to verify). Include an item only if it passes ALL four gates:
   • the next session must know it to continue;
   • the user confirmed it, or it is verifiable in code;
   • it is directly relevant to the current feature;
   • it reduces the next session's ramp-up cost.
4. Fill the template. Read assets/session-handoff-template.md and produce the complete 10-section document in that exact structure. HTML comments in the template are fill instructions: follow them, then remove them from the output.
5. Deliver according to the Output contract below.

Output contract

• Chat output (default). The final response is exactly one fenced code block containing the complete handoff document — no preamble before it, no commentary after it. Use a four-backtick outer fence (````markdown): the document contains triple-backtick blocks inside, and a triple-backtick outer fence would break nesting.
• File output (only when explicitly requested). Write the file and respond with a brief confirmation and the file path. Do not also print the full document unless the user asks for both. Save as session-handoff.md or handoff-<feature>.md. If the target file already exists, do not overwrite silently: ask the user first, or if asking is not possible, save under a numbered name such as session-handoff-2.md.
• One language throughout. Write the entire document in the session's main working language. The template's headings, the fixed source-of-truth statement, inline markers, and placeholder phrases such as "None recorded in this session" are English baselines — translate them all when the session language is not English. Keep the structure and section numbering unchanged.

Rules

• Keep only information useful for future implementation. Drop chit-chat, emotional remarks, low-value exploration, details of rejected approaches with no reference value, and duplicated information.
• Separate facts from decisions from assumptions. Never present an unconfirmed guess as a conclusion.
• Requirements vs decisions. A requirement is a behavior, constraint, or boundary that must hold — it goes in section 3. A decision is a chosen implementation direction with its reason and rejected alternatives — it goes in section 5. Never record the same fact in both sections; put it where it belongs and cross-reference ("see Decision N") from the other.
• Verification. In section 4, pair what was completed with how it was checked (command + result). If nothing was run, write "Not run in this session." — never imply verification that did not happen.
• Out of scope. Use section 8 to list adjacent work the next session must not start uninvited (README, CI, large refactors, repo-wide formatting, and similar).
• Source priority. When sources conflict, trust in this order: (1) the current code state, (2) the user's most recent explicit statement, (3) earlier session discussion. Record any conflict you find in section 7 instead of silently resolving it.
• Insufficient context. When a section has no reliable information, write "None recorded in this session" (translated into the output language) — never pad the template with invented content. If the gap matters, list it in section 7 or 9 as something for the next session to verify.
• Do not invent implementation details: nothing goes into "Completed" that did not actually happen in this session.
• Do not turn temporary ideas into permanent rules.
• The document MUST contain the source-of-truth statement, in the output language (English baseline: "If this document conflicts with the current code state, the code is the source of truth.").
• Do not modify any project files unless explicitly requested.