handoff

# Handoff > Write a compact, decision-ready handoff so the next session (or the user) > can continue without reconstructing the current one. Use when the session is > ending, context is running low, the user asks for a handoff / "pass the > baton" / "hand off", or a long-running operation needs a durable state > checkpoint. The goal: the durable artifact survives, the context does not > need to. Invocation: `model+user` ## When to use - The user says "handoff", "hand off", "pass the baton", "takeover prompt", "write me a handoff", or the session is about to end / compact. - A long operation (multi-turn, multi-workstream) has state that must survive context loss: commits, branches, PRs, CI, blockers, decisions. - You are switching to a fresh session and want the new session to start from evidence instead of reconstructing the old one. ## What to do 1. **Gather the truth from tools, not memory.** Run/collect: - `git branch --show-current`, `git status --short`, `git log --oneline origin/<default>..HEAD` (what is local-only), `git log --oneline -5` (recent context). - Live remote state where relevant (`gh pr list --state open`, `gh pr checks <n>`, `gh run list`) — only what the user's operation actually depends on; do not pad the handoff with a full GitHub dump. - Any in-flight work: dirty files, uncommitted slices, partial worktrees, running background jobs/workers, queued CI. 2. **Write a compact markdown handoff** (aim under ~60 lines; the user may also ask for a "short text-only" variant — then aim under ~15 lines): ```markdown # Handoff — <operation/session name> — <date> - **State:** <one-line: what is done vs in-flight vs blocked> - **Landed/committed:** <exact SHAs + one-line what> - **Branches/PRs:** <names + states; which are ours vs community> - **CI:** <what is green, what is waiting, what is broken> - **Blockers:** <exact blocker + what would unblock> - **Decisions made:** <the WHY that a fresh session must not re-litigate> - **Next step:** <the single next action, one line> - **Continuation records:** <pointers to partial work that must be preserved (worktrees, uncommitted files, receipts)> ``` 3. **Persist it.** Always write `.codewhale/handoff.md` in the workspace — that is the only path the runtime reads back. On the next session's first turn it is injected as the "## Previous Session Relay" block (`HANDOFF_RELATIVE_PATH`, `crates/tui/src/prompts.rs:85`; loader at `prompts.rs:301-315`). A handoff written anywhere else is never picked up, so the next session starts cold no matter how good the note is. Optionally also write a human-discoverable copy: - If the workspace has an ops/notes convention (e.g. `codewhale-ops/notes/` with a living handoff file), update the living handoff's dated facts and snapshot, or create `<topic>-handoff-<date>.md` next to it. - Otherwise the repo root as `HANDOFF.md` or `docs/handoff/<topic>-<date>.md`. These are for people; nothing in the runtime reads them. Never overwrite someone else's uncommitted handoff without reading it first. 4. **Clear the way for the new session ("clears context").** A skill cannot delete the current context, but it can make the context disposable: - Ensure nothing is left only in memory: dirty work is either committed (WIP is fine with a real body), stashed with a note, or recorded in the handoff with its exact location. - Kill or record background work that would outlive the session (background jobs, sub-agents) — record what is still running and its task id. - Close with the one-line "next step" so the fresh session has an unambiguous first action. 5. **Deliver.** Give the user the compact handoff text in your reply (the persisted file is the durable copy; the reply is the readable one). ## Constraints - Facts only from tool output; never invent SHAs, check states, or blockers. - Keep claims narrower than evidence: distinguish landed/committed, verified locally, CI-verified, and pending. - Preserve other people's uncommitted work: read before touching, archive before overwriting. - The handoff is orientation, not law: tell the next session to refresh live state before acting on it. - If the user asks for a "short text-only" handoff, give exactly that in the reply and skip the full markdown file unless asked.