Session Handoff

When this fires

A long session accumulates decisions, dead ends, and verified facts that live only in the conversation. When that conversation gets compacted or a new session has to pick up the work, all of that is at risk of being silently lost — the next session either re-derives it (slow) or contradicts it (worse). This skill's job is to decide, before the flush happens, exactly what is worth keeping and write it down in a form a cold session can use without re-reading the whole history.

Protocol

1. Detect the trigger. Confirm this is actually a long-session boundary: context-limit warning, explicit compaction, or the user asking to pause and resume later. Do not run this for a task that is about to finish.
2. Extract durable state only, pulling from the actual conversation — never from inference or assumption:
   • Architecture / design decisions that were made, and why
   • Edge cases or bugs already found (so they aren't re-discovered)
   • The file map: which files matter and what each one is for
   • Open threads: what's unfinished, blocked, or explicitly deferred
   • What's verified (ran, tested, observed) vs. assumed (stated but not checked)
3. Write HANDOFF.md (or, if no file should be written, print the same content as a block) using the fixed template in Output below.
4. List what can be safely dropped from context now that it's captured in the handoff — this is what makes the handoff worth writing.

Hard rules

• Never invent a decision, rationale, or fact that wasn't actually established in the session. If something is unclear, list it under Open Threads instead of guessing.
• Every claim goes in either Verified or Assumed — never blur the two.
• Keep the handoff under ~40 lines. If it's longer, cut detail, not sections — a bloated handoff defeats the purpose.
• Do not re-explain code that's readable from the files themselves; capture only what isn't recoverable by reading the repo (decisions, rejected approaches, in-progress state).

Output

A HANDOFF.md in this exact structure:

# Handoff: <task name>

## Decisions made
- <decision> — <why>

## Edge cases already caught
- <case> — <how it's handled>

## File map
- <path> — <role in this task>

## Verified vs assumed
- Verified: <what was actually run/tested/observed>
- Assumed: <what was stated but not checked>

## Open threads
- <what's unfinished, blocked, or deferred, and why>

## Safe to drop
- <context that's now fully captured above and doesn't need re-reading>