| 1 | --- |
| 2 | name: handoff |
| 3 | description: "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." |
| 4 | invocation: model+user |
| 5 | --- |
| 6 | |
| 7 | # Handoff |
| 8 | |
| 9 | > Write a compact, decision-ready handoff so the next session (or the user) |
| 10 | > can continue without reconstructing the current one. Use when the session is |
| 11 | > ending, context is running low, the user asks for a handoff / "pass the |
| 12 | > baton" / "hand off", or a long-running operation needs a durable state |
| 13 | > checkpoint. The goal: the durable artifact survives, the context does not |
| 14 | > need to. |
| 15 | |
| 16 | Invocation: `model+user` |
| 17 | |
| 18 | ## When to use |
| 19 | |
| 20 | - The user says "handoff", "hand off", "pass the baton", "takeover prompt", |
| 21 | "write me a handoff", or the session is about to end / compact. |
| 22 | - A long operation (multi-turn, multi-workstream) has state that must survive |
| 23 | context loss: commits, branches, PRs, CI, blockers, decisions. |
| 24 | - You are switching to a fresh session and want the new session to start from |
| 25 | evidence instead of reconstructing the old one. |
| 26 | |
| 27 | ## What to do |
| 28 | |
| 29 | 1. **Gather the truth from tools, not memory.** Run/collect: |
| 30 | - `git branch --show-current`, `git status --short`, `git log --oneline |
| 31 | origin/<default>..HEAD` (what is local-only), `git log --oneline -5` |
| 32 | (recent context). |
| 33 | - Live remote state where relevant (`gh pr list --state open`, |
| 34 | `gh pr checks <n>`, `gh run list`) — only what the user's operation |
| 35 | actually depends on; do not pad the handoff with a full GitHub dump. |
| 36 | - Any in-flight work: dirty files, uncommitted slices, partial worktrees, |
| 37 | running background jobs/workers, queued CI. |
| 38 | 2. **Write a compact markdown handoff** (aim under ~60 lines; the user may |
| 39 | also ask for a "short text-only" variant — then aim under ~15 lines): |
| 40 | |
| 41 | ```markdown |
| 42 | # Handoff — <operation/session name> — <date> |
| 43 | - **State:** <one-line: what is done vs in-flight vs blocked> |
| 44 | - **Landed/committed:** <exact SHAs + one-line what> |
| 45 | - **Branches/PRs:** <names + states; which are ours vs community> |
| 46 | - **CI:** <what is green, what is waiting, what is broken> |
| 47 | - **Blockers:** <exact blocker + what would unblock> |
| 48 | - **Decisions made:** <the WHY that a fresh session must not re-litigate> |
| 49 | - **Next step:** <the single next action, one line> |
| 50 | - **Continuation records:** <pointers to partial work that must be |
| 51 | preserved (worktrees, uncommitted files, receipts)> |
| 52 | ``` |
| 53 | |
| 54 | 3. **Persist it.** Always write `.codewhale/handoff.md` in the workspace — that |
| 55 | is the only path the runtime reads back. On the next session's first turn it |
| 56 | is injected as the "## Previous Session Relay" block |
| 57 | (`HANDOFF_RELATIVE_PATH`, `crates/tui/src/prompts.rs:85`; loader at |
| 58 | `prompts.rs:301-315`). A handoff written anywhere else is never picked up, |
| 59 | so the next session starts cold no matter how good the note is. |
| 60 | |
| 61 | Optionally also write a human-discoverable copy: |
| 62 | - If the workspace has an ops/notes convention (e.g. `codewhale-ops/notes/` |
| 63 | with a living handoff file), update the living handoff's dated facts and |
| 64 | snapshot, or create `<topic>-handoff-<date>.md` next to it. |
| 65 | - Otherwise the repo root as `HANDOFF.md` or |
| 66 | `docs/handoff/<topic>-<date>.md`. These are for people; nothing in the |
| 67 | runtime reads them. Never overwrite someone else's uncommitted handoff |
| 68 | without reading it first. |
| 69 | 4. **Clear the way for the new session ("clears context").** A skill cannot |
| 70 | delete the current context, but it can make the context disposable: |
| 71 | - Ensure nothing is left only in memory: dirty work is either committed |
| 72 | (WIP is fine with a real body), stashed with a note, or recorded in the |
| 73 | handoff with its exact location. |
| 74 | - Kill or record background work that would outlive the session |
| 75 | (background jobs, sub-agents) — record what is still running and its |
| 76 | task id. |
| 77 | - Close with the one-line "next step" so the fresh session has an |
| 78 | unambiguous first action. |
| 79 | 5. **Deliver.** Give the user the compact handoff text in your reply |
| 80 | (the persisted file is the durable copy; the reply is the readable one). |
| 81 | |
| 82 | ## Constraints |
| 83 | |
| 84 | - Facts only from tool output; never invent SHAs, check states, or blockers. |
| 85 | - Keep claims narrower than evidence: distinguish landed/committed, verified |
| 86 | locally, CI-verified, and pending. |
| 87 | - Preserve other people's uncommitted work: read before touching, archive |
| 88 | before overwriting. |
| 89 | - The handoff is orientation, not law: tell the next session to refresh |
| 90 | live state before acting on it. |
| 91 | - If the user asks for a "short text-only" handoff, give exactly that in the |
| 92 | reply and skip the full markdown file unless asked. |
| 93 |