Session Handoff Skill

Produce or update handoff.md at the project root: a compact, skim-friendly picture of the current situation so the next session is productive in seconds instead of minutes — without re-deriving what's already known or re-breaking what already works.

The richest source of material is this session's own recollection of what it did. Write the handoff right here in the main conversation — do not hand the authoring off to a subagent, which carries none of the conversation's context. Tools exist only to pull durable repo facts that confirm or correct that recollection.

A handoff is neither a changelog nor a memory dump. It exists to answer four things for whoever picks up next: Where do we stand? What just changed? What's still open? What's the first move? Anything that doesn't serve one of those gets cut.

Gather context first

This skill ships standalone, so it can't assume your project's conventions, house style, or preferences the way it could for its author. Before doing the main work:

1. Auto-detect what you safely can from the repo — language/stack, base branch, build/test commands, existing config and docs. Never ask for something you can read for yourself.
2. Ask, don't assume, for the rest. Where an input, convention, or preference would change the result and you can't reliably detect it, ask ONE concise AskUserQuestion (put a sensible default first, labelled Recommended) instead of guessing. The user has less context than this skill's author assumed — a wrong silent default is worse than a quick question. Don't ask about things you can detect, and don't ask more than you need.

For this skill, confirm up front (only the items you can't already detect):

• Output path & filename — default is handoff.md at the repo root; confirm if this project keeps continuation/session docs somewhere else or under a different name.
• Commit or leave uncommitted — auto-detect from .gitignore; handoff.md is usually per-session scratch left untracked, but confirm before staging if the project tracks such docs.
• Focus / scope — if $ARGUMENTS didn't name one, which in-flight thread the next session most needs carried forward (vs. a general "where we are" pass over everything).
• Where open work and durable notes live — which review / TODO / issue / notes files to point at; the house PLAN_REVIEW_* / REVIEWED.md / TODOS.md names may not exist here, so point at whatever this project actually uses instead of inventing them.

Step 0 — create vs update

Look for handoff.md at the repo root (ls handoff.md):

• Found → UPDATE it in place. Do NOT overwrite wholesale. The expensive part is the operational context — re-verify commands, infra coordinates, traps, "do NOT do X" warnings — and preserving whatever is still true is the entire point. Then: refresh the dated header; swap "What shipped" for this session's work; re-confirm or explicitly mark stale every runtime value the previous handoff stated; carry over still-open follow-ups and drop the resolved ones; rewrite "Next session". If this session disproved something the old handoff claimed, call it out (~~old~~ → corrected: …) rather than quietly replacing it.
• Missing → CREATE one from the template below.

If $ARGUMENTS points at a focus (e.g. handoff focus on the migration), tilt the doc toward that thread while still answering all four questions.

Step 1 — gather the state (facts, not impressions)

Replay the current conversation for what genuinely happened this session, then check it against the repo:

git branch --show-current
git log --oneline -15
git status --short
git log --oneline @{upstream}..HEAD 2>/dev/null                 # unpushed local commits
gh pr list --state open   --limit 10 2>/dev/null                # open PRs
gh pr list --state merged --limit 8  2>/dev/null                # recently merged
ls *REVIEW*.md REVIEWED.md TODOS.md handoff.md 2>/dev/null       # review artifacts + existing todos

Draw on these, highest priority first:

1. The conversation itself — what got decided, built, fixed, deferred, and why. Only the live session holds this, which is exactly why this skill can't run as a subagent.
2. Open-work trackers — whatever this project actually uses: a TODOS.md, review files (PLAN_REVIEW_*.md, SCOPE_REVIEW_*.md, REVIEWED.md if present), GitHub issues, or a NOTES.md. Detect what exists rather than assuming the house review-file names; cite them by name and don't restate what they already contain.
3. Durable project notes — any long-lived memory or notes file the project keeps for facts already recorded. Link to them; never copy their contents across.
4. Deploy / runtime surface — if the project has a deploy.sh, an infra/ directory, or any live/deployed component (the project's CLAUDE.md or README usually says), capture the Current state section. For a library or CLI with no runtime, skip it and note build/test status instead.

Confirm every cited fact before it goes in — PR numbers, commit SHAs, file paths, host IPs, env-flag values. A handoff that points the next session at the wrong place, branch, or box is worse than none at all. For any runtime value you can't re-confirm right now, record it as (last verified <date>, re-check before trusting) rather than asserting it as current.

Step 2 — write the handoff

Front-load whatever prevents wasted effort and broken things. Trim the rest. Aim for ~1–2 screens; a handoff nobody reads is dead weight. Include only the sections that apply:

# Session Handoff

**Date:** <absolute date or range, e.g. 2026-06-24>
**Branch:** <branch> — <clean / open feature branch / everything merged>
**State:** <one line: is it deployed/live/healthy? or for non-runtime projects: tests green, build OK, mid-refactor?>

---

## TL;DR
<3–6 sentences. The paragraph to read if you read nothing else: where things stand,
what this session changed, and the single most important thing to know going in.>

## Current state — verify before trusting   ← only if there's a live/deployed/stateful component
- **Infra:** <host, key, dir, the env flags that matter>.
- **Last verified (<timestamp>):** <the values an operator would trust and act on>.
- **Re-verify:** `<the exact command to re-check the above>`
  (State is stale the moment it's written — this line is mandatory for anything live.)

## What shipped this session
| PR / commit | Content |
|---|---|
| #NN (merged) | <one line> |
| `<sha>` | <one line> |

## Open follow-ups
- <unresolved item> → tracked in `TODOS.md #N` / issue #N / `<review file>`. (Point, don't re-explain.)

## In-flight / not landed
- <branch or research track>: <what's done, what's left, how to resume it>.

## Gotchas / notes
- <trap that bit you this session, environment quirk, or an explicit "do NOT do X — it Y">.

## Next session — start here
1. **<the single highest-priority next action, named concretely>** — <why / first command>.
2. <next>…

Style

• Skimmable: short bullets, bold the load-bearing words, tables for PR lists.
• Absolute dates only (turn "yesterday" / "next week" into actual dates).
• Provenance refs (PR numbers, commit SHAs, ticket IDs) are welcome here — handoff.md is throwaway per-session scratch, so naming them costs nothing. The code those refs point at, though, should still read clearly on its own.
• Name the one thing to tackle first, in plain terms. "Various cleanup remains" helps no one.
• Don't pad for the appearance of thoroughness. A small session earns a small handoff.

Output

Write handoff.md to the repo root (or wherever this project keeps continuation/session docs, if it has a different convention — confirm rather than guess). Print a 2-line confirmation: what it now covers plus the named first step for next time. Do not commit it unless asked — handoff.md is usually left uncommitted (or gitignored) as per-session scratch; check .gitignore and the repo's convention before staging.

When this fires on its own

It pairs well with context pressure: when a session has run long and is nearing compaction, offer to write the handoff before the context is lost. It complements any durable project-notes update — those hold the long-lived facts, while the handoff captures the volatile "where we are right now" the next session needs. Don't auto-write without a prompt; offer first.