# Handoff

> Write an end-of-session handoff note — what changed, what's half-done, what's risky, exact next steps — for a teammate or future self. Use at the end of a work session, before a vacation, or when transferring work-in-progress to someone else.

- Skill: `tokyubevoxelverse/handoff` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tokyubevoxelverse/handoff`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tokyubevoxelverse/handoff/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tokyubevoxelverse (https://skillmd.com/u/tokyubevoxelverse)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tokyubevoxelverse/handoff

---


# Handoff

Whoever picks this up next — a teammate tomorrow, the user in three weeks — arrives with zero short-term memory of today. Your job is to write the note that makes their first thirty minutes cost five. Write for a competent stranger: no "as discussed," no "the usual place," no pronouns pointing at things only today's session can see.

## Gather evidence first

Don't write from memory — write from the actual state: `git status` and the full working diff, recent commits since the last pushed/shared point, stashes (people forget stashes exist — surface them), test-suite status *run now* (not recalled), TODO markers added today, and anything relevant from the working session (decisions made, approaches rejected and why).

## The note

Write `HANDOFF.md` (or print, if the user prefers):

**1. TL;DR** — three sentences max: what this work is, where it stands, what happens next.

**2. What changed and why** — grouped by intent, not by file ("reworked session expiry to fix the logout bug" — then the files under it, as `path:line` references). Include the *why* for anything a reader would question; the why is precisely what evaporates overnight.

**3. Half-done** — the most valuable section; be brutally honest. For each incomplete piece: exact current state, what remains, and the *gotcha that isn't written down anywhere else* — the insight currently living only in working memory ("the migration is written but not run", "renamed in the callers but not the tests", "this approach works but I was about to abandon it because…").

**4. Landmines** — things that look done but aren't; temporary hacks that must not ship (with locations); anything that will bite the next person if touched naively ("the seed data is hand-edited, regenerating overwrites it").

**5. Next steps** — an ordered list where each item is executable without archaeology: the exact command, the exact file and function, the specific decision to make with the options laid out. "Continue the refactor" is banned; "extract the retry logic in `sync.js:140-180` into `lib/retry.js`, then update the three callers listed below" is the standard.

**6. How to verify where things stand** — the commands that prove the current state (build passes? which tests are red *right now* and which reds are expected?), so the next person can distinguish inherited breakage from breakage they caused.

**7. Rejected paths** — approaches tried and abandoned this session, one line each with the reason. This is the section that saves the next person from re-losing the same afternoon.

## Rules

- Never claim work is done that wasn't verified this session — a handoff that oversells state is worse than none.
- If tests are failing, the note says so with the failure names. Honesty over tidiness.
- Length follows entropy: a clean stopping point earns a short note; a messy mid-refactor state earns a long one. Never pad, never truncate the mess.