Session handoff

Session Handoff

Write a grounded handoff document — and a one-line continuation memory — so a fresh session can resume exactly where this one left off.

Announce at start: "I'm using the session-handoff skill to write a session handoff."

Human-invoked only. A human fires this skill directly (slash command or explicit ask) — before /clear, /compact, a context limit, or a teammate handoff. It stays off every agent-trigger surface by design.

When a human uses this

• Before /clear or /compact, mid-task, when context is about to be lost.
• End of a working session, to seed the next one.
• Handing work to a teammate or another agent.

Optional argument: a short description of what the next session will focus on — used to tailor Work In Progress / Loose Threads / Suggested Skills.

Pipeline

1. Gather (read-only, run the commands — do not recall): git status -sb, git log --oneline -15, git diff --stat, branch + ahead/behind; bd ready, bd blocked, bd count --by-status, in-progress beads; list the spec, plan, and architecture-decision-record files touched this session. Done when: every listed command has run and its output is captured.
2. Synthesize into the bundled template (handoff-template.md). Reference artifacts by path — never paste their bodies (commits, ADRs, specs, plans, diffs). Duplicating bloats the doc and goes stale. Done when: every section maps to a captured fact, referenced by path.
3. Write the doc — Default: .internal/handoff/YYYY-MM-DD[-HHMMSS]-<topic>-handoff.md (-HHMMSS only if a same-day handoff exists). (The same-day check globs the inbox .internal/handoff/*.md only; archived docs under archive/ are out of scope and do not affect same-day naming.) If the human names another location, write there. mkdir -p the target first. Done when: the doc exists at the target path.
4. Write the continuation memory — bd remember "continuation-<date>-<topic>: <one-line pointer to doc path + headline state>" (episodic continuation record; one-line pointer only). Done when: bd remember has run for the continuation key.
5. Verification (externally anchored — output the result block):
   • Cross-check each state line against the captured Phase-1 command output.
   • Gitignore safety: git check-ignore <output-path>; if NOT ignored, warn the human ("⚠️ <dir> is not gitignored; a handoff can contain sensitive session state") and offer to add it to .gitignore before writing.
   • ls <path> confirms the doc exists; bd memories <key> confirms the memory.
   • Secret-scan grep over the doc (sk-, ghp_, AKIA, -----BEGIN, password=) — a backstop, not a guarantee.
   • The narrative synthesis is the author's recollection — not externally verified; that is why it references artifacts by path. Done when: the confirmation block is output — doc path · memory key · gitignore-safety result · secret-scan result.

Doctrine

• Redact secrets (keys, tokens, passwords, PII) — the doc lands on disk and may be shared. This is a hard rule; never weaken it.
• Reference, don't duplicate — point at commits/ADRs/specs by path.
• Ground every fact — run the gather commands; never invent state. If a command fails (not a git repo, bd absent), degrade gracefully and note the gap.

Red Flags (low-independence backstop — not the primary guard)

Rationalization	Reality
"I'll write it from memory"	Run the gather commands — recollection drifts.
"I'll add it to the skill index so the agent finds it"	Forbidden — human-invoked only.
"The output dir is probably gitignored"	Run git check-ignore — secrets to a tracked path is a leak.

Integration

Standalone. Human-invoked only, with no skill, hook, or agent-routing surface pointing to it. Read-side counterpart: getting-up-to-speed reads the latest .internal/handoff/ doc (no skill-to-skill call) and archives it to .internal/handoff/archive/ on close — .internal/handoff/ is an unread inbox, so a stale doc is never re-read as the last session.