---
name: session-handoff
description: "Write a handoff + changelog document that captures the current session's work before context is cleared or handed to another agent/session. Use when the user says handoff, changelog, hand off, session summary, wrap up, write a handoff, before /clear, document what we did, or is about to reset context and wants continuity. Produces a single markdown file: what changed (changelog), current verified state, open items, non-obvious decisions/gotchas, and how to continue — so the next session resumes without re-deriving everything."
---

# Session Handoff

## Purpose

Before a context clear (`/clear`), the end of a work session, or a hand-off to another
agent, capture everything the next session needs so it resumes instantly instead of
re-discovering the work. Produces one markdown handoff/changelog file. Optionally updates
memory for cross-session facts.

A good handoff answers: **what changed, what's the state now, what's left, and what would
bite someone who didn't live through this session.**

## When to use

Trigger on "handoff", "changelog", "wrap up", "session summary", "before /clear", "document
what we did", "hand this off", or whenever the user is about to reset context and wants
continuity. Also good proactively at the end of a large multi-step task.

## How to use

### 1. Gather the facts (don't rely on memory of the chat — verify)

Run `scripts/collect-context.sh` (in the repo) to dump git/PR context, or gather manually:
- **Changed/created files** this session (git status, recent commits).
- **PRs/branches** opened, merged, closed (`gh pr list`, `gh pr view`).
- **Commands that verified success** (tests, typecheck, curl, API calls) and their results.
- **Decisions made** and the reasoning — especially ones that aren't obvious from the code.
- **Dead ends / things deliberately NOT done** and why (prevents the next session redoing them).

Verify claims against reality (re-read a file, re-check a PR state) rather than trusting the
conversation — merges/edits may have happened out of band.

### 2. Write the handoff

Copy `assets/handoff-template.md`, fill every section, drop sections that don't apply. Save to
a sensible, discoverable path:
- Repo work → `docs/handoff-<topic>-<YYYY-MM-DD>.md` or `<TOPIC>-HANDOFF.md` at repo root.
- If the repo has a docs/ convention, follow it.

Write in normal prose (this is a persisted doc, not chat). Be concrete: real paths, real PR
numbers, real command lines, real values (mask secrets — reference where they live, never paste
key material).

### 3. Key content rules

- **Changelog = what changed**, grouped and scannable (a table or bullet list per area). Include
  PR numbers and file paths.
- **Current state = what's true now**, verified (merged/deployed/passing), not "should be".
- **Open items** split into: actions for the **user/human** (add secrets, click merge, deploy)
  vs. work for the **next agent** (build X, fix Y). Order by priority.
- **Gotchas & non-obvious context** — the highest-value section. Race conditions, why an
  approach was chosen, data quirks, things that look wrong but aren't. This is what a fresh
  agent can't infer from the diff.
- **How to continue / reproduce** — exact commands, entry points, where the next agent picks up.
- **Honest limitations** — what's incomplete or approximate, so no one over-trusts it.

### 4. Update memory (optional but recommended for durable facts)

If the session produced facts that outlive this handoff (architecture, credentials locations,
recurring gotchas, project decisions), also write/update memory files so future sessions load
them automatically — the handoff doc is point-in-time; memory is standing.

## Bundled resources

- `assets/handoff-template.md` — the fillable template. Copy it, fill, save.
- `scripts/collect-context.sh` — dumps git status, recent commits, and (if `gh` is available)
  open/recently-merged PRs, to seed the changelog. Run from the repo root:
  `bash <skill>/scripts/collect-context.sh [since-ref]`.