Session Handoff Notes skill for Claude Code
Resume long tasks in minutes, not another hour of digging. Writes the note a fresh session or a teammate needs to pick up a long task immediately. Claude gathers the real state from git and test runs instead of memory, separates verified work from assumptions, records half-finished files with line numbers, failed approaches and traps, asks what to do with uncommitted changes, and proves the note works by having a context-free reader name the next action.
- name
session-handoff-notes - size173 lines · ≈1,700 tokens
- files1
- licenseMIT
- updated
What Claude sees before loading it
This description is the only part of the skill that sits in context all the time. Claude reads it to decide when to load the full playbook below.
description: Writes handoff and progress notes that let a later Claude Code session or a teammate resume a long task without re-discovery, capturing goal, verified state, uncommitted work, decisions with rejected alternatives, traps found, exact next step, and a resume prompt, then checks the note with a cold read. Use when ending a session mid-task, before clearing context on multi-day work, handing work to someone else, when blocked, or when the user says "write a handoff", "save progress", or "pick up where we left off".Try asking
- Write a handoff so tomorrow's session can continue this migration
- I'm passing this branch to Priya — leave her everything she needs
- Save our progress before I clear the context
Use it when
- A session ends with the task unfinished
- Work is moving to a teammate or another session
- You are about to clear context on multi-day work
- Progress is blocked waiting on someone else
Skip it when
- Managing the current session's context without a break — use context-window-hygiene instead
- Planning work that has not started yet — use task-decomposition-plans instead
How to check the result
A fresh session given only the note states the goal, the next action and how to confirm it, and the note's description of uncommitted work matches git status.
The common mistake it prevents
Leaving out the approaches that already failed, so the next session spends an hour rediscovering the same dead ends.
A handoff is good when a reader with zero context, a fresh session or a teammate, can resume within five minutes without re-reading the codebase or repeating a failed attempt. That requires facts, not narrative: what is done and proven, what is half-done and where, what was tried and rejected, and the single next action.
When to write one
- Ending a session with the task unfinished.
- Before
/clearor a fresh session on work that spans days. - Handing work to a teammate or to a parallel session.
- When blocked on someone else (a decision, access, a review).
- After an expensive investigation whose conclusions should not be lost.
Where it goes
| Reader | Location |
|---|---|
| Future you / future session, same machine | .claude/handoff/<branch-or-task>.md (gitignored) |
| Teammate on the same branch | The PR description or a committed docs/handoff/<task>.md |
| Teammate picking up an issue | A comment on the issue |
| Parallel worktree sessions | One note per worktree, named by branch |
One note per task. Rewrite it in place each time; do not append a diary.
Workflow
- [ ] 1. Gather the real state with commands (never from memory)
- [ ] 2. Run the checks that prove what "done" parts actually work
- [ ] 3. Decide what happens to uncommitted work (ask the user)
- [ ] 4. Write the note from the template
- [ ] 5. Cold-read test it
- [ ] 6. Tell the user where it is and the resume prompt1. Gather state
git branch --show-current
git status --short
git log --oneline origin/main..HEAD # commits on this branch
git diff --stat # uncommitted changes
git stash list # stashes that would be forgottenAlso collect: the failing test names and exact error text, commands that worked, URLs of related PRs/issues, environment details that mattered (ports, seeds, feature flags).
2. Prove before claiming
Run the tests or checks for everything you will mark as done. Write the result with the command. “Tests pass” without a command and a date is a guess, and the next session will trust it.
3. Uncommitted work
Ask the user whether to make a WIP commit on the branch, leave changes in the working tree, or stash them. Record the choice in the note. Never leave meaningful work only in a stash or in a worktree that may be removed without saying so in the note.
4. Template
# Handoff: <task name>
Updated: 2026-10-19 by <session/person> | Branch: feat/pi-checkout | HEAD: 3f9c2a1
## Goal
Switch checkout from Stripe Charges to Payment Intents behind flag `pi_checkout`.
Done when: e2e `checkout.spec.ts` passes with the flag on and off; no Charges calls with flag on.
## Status
In progress: 3 of 5 steps done. Blocked: no.
## Done (verified)
- PaymentIntent wrapper `src/billing/intents.ts` (commit a1b2c3) - `pnpm test:billing` green 2026-10-19
- Webhook handler for `payment_intent.succeeded` (commit d4e5f6) - verified with `stripe trigger`
## In progress
- `src/checkout/submit.ts:88-140` half-migrated; uncommitted (WIP left in working tree per user)
- Failing: `checkout.spec.ts > applies coupon` - "Expected amount 1800, received 2000"
## Next step
Apply the coupon discount before creating the intent (`submit.ts:102`), rerun
`pnpm playwright test checkout.spec.ts`.
## Decisions (and rejected options)
- Webhook-first confirmation; rejected client-side confirmation (race with redirect).
- No backfill of historical charges; finance confirmed (issue #231).
## Traps found
- Stripe test clock must be reset between e2e runs: `pnpm stripe:reset-clock`.
- `amount` is integer cents everywhere; `formatMoney` expects cents, not dollars.
## Unverified / assumptions
- Refund flow untouched by this change - not tested yet.
## How to run
`pnpm dev` (port 3000), `stripe listen --forward-to localhost:3000/api/webhooks`, `pnpm test:billing`
## Open questions
- Should 3DS-required cards fall back to Charges while the flag rolls out? (ask @dana)
## Resume prompt
"Read .claude/handoff/pi-checkout.md, confirm HEAD is 3f9c2a1 and the coupon test still
fails the same way, then do the Next step."Writing rules:
- Exact identifiers: file paths with line numbers, test names, commands, error text, commit SHAs. “The checkout file” is useless to a cold reader.
- Mark confidence: put anything not run or not checked under “Unverified”.
- Record failed approaches and why they failed, or the next session will retry them.
- Keep it under ~80 lines. Link long investigation logs rather than pasting them.
- No secrets. Point to where a secret lives (“1Password: stripe-test”), never the value.
5. Cold-read test
Give the note to a reader with no context (a fresh session, or a subagent with only the note and repo access) and ask: “What is the goal, what is the next action, and how will you know it worked?” If the answer is wrong or needs exploration, the note is missing a fact. Fix the note, not the reader.
Resuming from a note
- Read the note.
- Check it is current: branch and HEAD match, the listed failure still reproduces, uncommitted changes are as described.
- If reality differs, reconcile first (someone pushed, tests changed) and update the note before continuing.
- Do the next step; update Status and Next step as you go.
- When the task is finished, delete the note or fold the durable parts (decisions, traps) into the PR description, CLAUDE.md, or docs.
To have new sessions pick the note up automatically, a SessionStart hook can print it
into context (see hooks-automation).
Gotchas
- A diary (“first I looked at X, then…”) buries the state. Write the current state, then the history only as decisions and rejected options.
- Claiming “almost done” without listing what remains. Every remaining item goes under Next step or In progress.
- Stale notes outliving the task mislead the next person. Delete on completion.
- Forgetting environment state that took effort to set up (seeded data, running containers, a feature flag toggled locally).
- Notes in a gitignored path are invisible to teammates; use the PR or issue for them.
Verification
- Every “Done” item has a command and result; every in-progress item has a path with line numbers.
git statusand the note agree about uncommitted work.- The cold-read test produces the correct next action without exploration.
Output
Reply to the user with:
**Handoff written:** .claude/handoff/pi-checkout.md (62 lines)
**State:** 3/5 steps done and verified; WIP in working tree (submit.ts), 1 failing e2e test recorded
**Cold read:** fresh session identified the next step and verification command correctly
**Resume with:** "Read .claude/handoff/pi-checkout.md, verify HEAD 3f9c2a1, then do the Next step."About this skill
Written and maintained by the Claude Skills editors to the same editorial standard as every skill in the directory: a selective trigger, a real workflow, known pitfalls and a verification step. First published , last updated . MIT licensed.