handoff git:20260725.3f0d943A

Immutable. This exact content is served forever at /api/v1/blob/16999213ce722460.

---
name: handoff
description: >
  Write a structured handoff document before a session ends, before a
  context-heavy interruption (SSH/tmux disconnect, context running low, a
  worktree being handed to another worker or agent), or when explicitly
  asked for a handoff — captures progress, what worked/failed, and the exact
  next step so a fresh session can resume without re-deriving context. Own
  version of the dx plugin's `/dx:handoff`.
---

# Handoff

A handoff doc exists to save the *next* reader (a fresh session, a different
agent, or you tomorrow) from re-deriving everything this session already
figured out. Write for someone with zero memory of this conversation, not a
recap for someone who was watching.

## What to include

- **Goal.** One sentence: what this session was actually trying to accomplish.
- **Done — verifiably.** What's complete, stated as a fact a reader can check
  (a commit hash, a passing test name, a file path with the final content) —
  not "implemented X" without a way to confirm it.
- **In-flight / blocked.** What's partially done, and specifically *why* it
  stopped — a failing test with its actual output, a decision waiting on the
  user, an external dependency not yet available. "Ran out of time" without a
  concrete blocker is not useful to the next reader.
- **Explicitly not done.** Anything the goal implies but this session didn't
  touch — cheap to state, expensive for the next reader to discover by
  assuming it's covered.
- **Next concrete step.** Not "continue the work" — the literal next action:
  which file, which command, which decision needs making first.
- **Decisions made and why.** Only the ones that weren't obvious — a
  constraint that ruled out the default approach, a tradeoff chosen
  deliberately. Skip anything a reader could re-derive from the diff itself.

## Where it goes

Don't silently create or overwrite a tracked file. Ask where it belongs if
unclear, or default to an untracked scratch location (e.g. a `HANDOFF.md` at
the repo root, gitignored, or the session's own scratchpad) — a handoff doc
is working state, not something that should land in a PR by accident.

## Keep it short

If the honest answer to "what's done" is "everything, cleanly" — say that in
one line and stop. A handoff doc's value is proportional to how much
re-derivation it saves, not its length.