Session Handoff

---
name: session-handoff
description: A human-invoked utility that writes a grounded session-handoff document (plus a continuation pointer memory) so a fresh agent can resume in-progress work. Not auto-invoked; a human runs it deliberately.
disable-model-invocation: true
---

# 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.