# Handoff

> MasterMind: Handoff

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

---


# MasterMind: Handoff

Context is the fundamental constraint (`~/.mastermind/engineering/core/agent-loop.md`); a long task shouldn't lose its thread to a
reset. Capture just enough to resume cold: high signal, low tokens.

## Capture

1. **Goal**: the outcome being built, in one line.
2. **State**: Done / In-progress / Next, as a short checklist. Be honest about what's *not* verified.
3. **Key decisions & why**: the non-obvious choices and their rationale (so they aren't relitigated).
4. **Map**: where the relevant code/files/config live; the entry points.
5. **Gotchas**: traps, failing things, env quirks, anything that bit you.
6. **How to resume & verify**: the exact command(s)/check to pick up and confirm green.

## Rules
Summarize and link, point to detail rather than pasting it. Write it where the next session
will look (`.mastermind/HANDOFF.md`, a scratch file, or the issue). Prune it when the work completes.

## Output
A tight `.mastermind/HANDOFF.md`: goal, state checklist, decisions, file map, gotchas, resume+verify steps.

## The ledger: for work that outlives one context window

A handoff is written once, at the pause. A **ledger** runs the whole way through: an append-only record
of what has actually been completed, so a long task can lose its thread without losing its place. Start
one when the work will be summarized more than once.

- **First line names the work**: the plan, spec, or issue it belongs to. A ledger nobody can match to
  a plan is a page of orphaned sentences.
- **Append one line as each step completes**: what was done, and the check that proved it. **Earlier
  entries are never rewritten or tidied:** it is a record of what happened, not a plan of what will.
- **Conversation memory does not survive compaction: trust the ledger and the git log over your own
  recollection**, most of all when you feel certain. Re-doing finished steps is the costliest failure in
  long-horizon work, and it always arrives wearing *"I remember doing that."* Read the record, then act.

Same instinct as the episodic journal appended at each verdict (`~/.mastermind/engineering/core/rigor.md`),
one level down: the journal spans tasks, the ledger spans steps inside one.