Context that survives /clear. A skill for Claude Code: the next session — an agent with zero context — starts working in 30 seconds instead of re-reading your codebase.
A handoff is not a session log. It is an executable brief: a living header edited in place on every update, with an append-only log at the bottom that the reader may ignore.
flowchart LR
A[Session running] -->|"/clear, /compact,<br/>stage done, context full"| B[WRITE]
B --> C[["handoff.md<br/>survives the reset"]]
C --> D[RECEIVE]
D -->|"verify predicates<br/>against reality"| E{Match?}
E -->|drift| F[Fix, note it]
E -->|broken premise| G[Report, ask]
F --> H[First action]
G --> H
H -->|"what was missing<br/>goes back into the file"| C
The loop is the point: every receive writes back what the handoff lacked, so the next one is better.
---
status: in progress
summary: parser v2 — migrating the tokenizer
updated: 2026-08-01
---
# Parser v2
**Plan:** .claude/specs/parser.md — stage 3/5, next task 3.2
## Continue work
**First action:** run `pytest -k parser` — 2 tests fail, fix `src/parser.py`
**DoD:** the `[DoD]` predicate below returns `0 failed`
## Map
- `src/parser.py` — anchor `def parse_v2`, the migration target
## Do not do
- Rewriting the lexer — tried, breaks the incremental path
## Expected state of the world
- `git rev-parse --abbrev-ref HEAD` → `feat/parser-v2`
- `[DoD]` `pytest -k parser -q` → now `2 failed` (expected — that's the work)The receiver runs those predicates before touching anything. Deterministic verification, not vibes.
| Mechanism | Problem it solves |
|---|---|
| Publicity gate | A handoff must never ride out on a public push. Checked via .gitignore before writing, with project memory as the fallback |
| Expected state of the world | 3–5 command → output predicates recorded from life. The receiver compares against reality instead of trusting prose |
| Drift vs broken premise | A failed predicate classifies itself: fix silently, or stop and report. More than half failing = wholesale breakage, however minor each looks |
| Grep anchors, not line numbers | Line numbers rot between sessions. file + unique substring survives refactors |
| Ownership check | Compares updated on disk against what was read at session start — a parallel session's edits are never silently clobbered |
| Receipts | The receiver writes what was missing into the file. A receipt in chat dies with the session |
| Cold-start test | The author must reread the header as an agent with zero context before finishing |
| Emergency write | A malformed tool call means every extra call risks repeating it — one Write, no verification steps |
Three findings drove the design:
- Across 36,611 production messages, all three vendor compactors scored 2.19–2.45 out of 5.0 on tracking which files were modified — precisely what the Map holds. (Factory.ai evaluation)
- Freeform summaries silently discard precise technical details; raw and structured storage beat summarization on recall benchmarks (77.9% vs 70.1%). (arXiv 2603.02473)
- Anthropic's own guidance: keep "the smallest possible set of high-signal tokens" and hold identifiers — paths, anchors — rather than copies. (Effective context engineering)
So the Map stays even when the file is trimmed; the log is cut first.
git clone https://github.com/Socialpranker/handoff-skill ~/.claude/skills/handoffProject-scoped instead: copy SKILL.md and references/ into .claude/skills/handoff/ at the repo root.
Then just say /handoff, or let it fire on its own when a session ends.
Nothing is required. If your setup has these, the skill defers to them instead of duplicating:
- a daily wrap-up skill · a memory system and its curator · a periodic memory-cleanup skill
Missing? Those steps are skipped and the core — write, receive, emergency write — works unchanged.
Do whatever you want with this.