| 1 | --- |
| 2 | name: cw-handoff |
| 3 | description: "Use when writing a Codewhale takeover prompt, continuation note, or end-of-session summary for another agent or a later session: a paste-ready handoff grounded in live state, with done/suspected/blocked kept separate." |
| 4 | --- |
| 5 | |
| 6 | # cw-handoff |
| 7 | |
| 8 | A handoff is read by an agent with none of your context and every incentive to |
| 9 | believe you. That makes an optimistic handoff worse than no handoff: it converts |
| 10 | your guesses into the next session's premises. Write it so the reader can |
| 11 | re-derive the state instead of trusting the prose. |
| 12 | |
| 13 | Stage 6 of the loop, and the one that makes the loop a loop: the next session |
| 14 | starts at [cw-orient](../cw-orient/SKILL.md) with what you leave here. |
| 15 | |
| 16 | ## When to use |
| 17 | |
| 18 | - Ending a session with work in flight. |
| 19 | - Asked for "a prompt for another agent", branch takeover instructions, a |
| 20 | continuation note, or a summary of current state for async work. |
| 21 | - Handing a lane to a different model, a fleet worker, or a remote session. |
| 22 | |
| 23 | ## Workflow |
| 24 | |
| 25 | 1. **Write it as a prompt the next agent can paste directly.** Not a report |
| 26 | about the work — instructions for continuing it. |
| 27 | |
| 28 | 2. **Open with the refresh block, not with your summary.** The first thing the |
| 29 | reader should do is verify you: |
| 30 | ```bash |
| 31 | cd <repo path> |
| 32 | git status --short --branch && git branch --show-current |
| 33 | git log --oneline --decorate -20 |
| 34 | git worktree list |
| 35 | ./scripts/release/check-versions.sh |
| 36 | ``` |
| 37 | Tell them to trust that output over anything below it. |
| 38 | |
| 39 | 3. **Cover these, in whatever order fits; drop sections that are empty:** |
| 40 | - Repository path and expected branch or worktree. |
| 41 | - The authority line: what they may and may not do without asking. Default to |
| 42 | local-only — no push, merge, tag, publish, GitHub Release, or destructive |
| 43 | cleanup without explicit approval. |
| 44 | - Durable files to read, ordered by importance: the scoped `AGENTS.md` for |
| 45 | the area, then the specific docs (`docs/CACHE.md`, |
| 46 | `docs/MOTION_CONTRACT.md`, `docs/ARCHITECTURE.md`, `crates/tui/AGENTS.md`) |
| 47 | the task actually touches. |
| 48 | - Commits already landed, with SHAs. |
| 49 | - **Dirty worktree caveats, naming uncommitted files explicitly**, and whose |
| 50 | they are. This is the single most useful line in most handoffs. |
| 51 | - The next slices, in priority order, each bounded the way |
| 52 | [cw-slice](../cw-slice/SKILL.md) bounds one. |
| 53 | - The verification gate for those slices — the smallest correct one from |
| 54 | [cw-gates](../cw-gates/SKILL.md), plus any known-flaky names. |
| 55 | - Open decisions that genuinely belong to Hunter. |
| 56 | |
| 57 | 4. **Separate three states, and never blur them:** *done and verified* (with the |
| 58 | command output that proves it), *suspected* (a hypothesis, labeled), and |
| 59 | *blocked* (with what unblocks it). If you did not run it, it is not done. |
| 60 | |
| 61 | 5. **Say what the branch is for.** Local-only, pushed for backup, or intended to |
| 62 | stay unpushed — the next agent cannot tell from `git` alone, and guessing |
| 63 | wrong is how work gets force-pushed away. |
| 64 | |
| 65 | 6. **Record missing external receipts.** If the task was local-only, say which |
| 66 | evidence you could not gather (CI state, registry state, review threads) |
| 67 | rather than inferring it. A named gap is useful; a confident guess is not. |
| 68 | |
| 69 | ## Red flags / don't |
| 70 | |
| 71 | - Don't imply publication happened unless you verified registry, tag, or release |
| 72 | state live. |
| 73 | - Don't hand off a narrative. Prefer concrete paths, commands, and SHAs. |
| 74 | - Don't summarize away the dirt. Unnamed uncommitted files get destroyed. |
| 75 | - Don't hand the next agent decisions you could have made. Reserve Hunter-facing |
| 76 | choices for product direction, irreversible actions, and visual judgments that |
| 77 | need eyes. |
| 78 | - Don't copy a previous handoff's state forward. Re-derive it; that is what |
| 79 | step 2 is for. |
| 80 | - Don't include secrets, tokens, or provider credentials in a handoff file. |
| 81 | |
| 82 | ## Output |
| 83 | |
| 84 | A single paste-ready block with the default shape — refresh commands, |
| 85 | authority line, files to read, landed SHAs, named dirty files, prioritized |
| 86 | next slices, the verification gate, and the open decisions — with done / |
| 87 | suspected / blocked visibly separated. Compress when trivial, but never |
| 88 | compress away the state separation: that is what keeps guesses from |
| 89 | becoming the next session's premises. |
| 90 |