| name | handoff |
| description | Bridge a long task across sessions. Invoke when the context window is filling up and you want to continue the SAME work in a fresh session — it writes a complete, self-sufficient handoff document ("hand off", "save state / context", "running low on context", "continue this later / in a new session"). Also invoke at the START of a new session to pick up from one ("resume", "pick up <topic>", "continue the handoff"). Two modes: HAND-OFF (write the doc) and PICK-UP (read it and continue). |
Session handoff
Carries long-running work across a context-window boundary so a fresh session continues seamlessly. Two modes — HAND-OFF (write a doc) and PICK-UP (resume one).
Decide the mode
Explicit words always win: "hand off / save state / running low on context" → HAND-OFF; "pick up / resume / continue" → PICK-UP. Otherwise infer from the session, and default to PICK-UP in a fresh session:
- Fresh session — you've done little/no substantial work yet this turn — AND a handoff doc exists → PICK-UP (resume the most recent one). This is the default at the start of a new session.
- Deep in a task — lots already done this session, context filling up → HAND-OFF (write the doc).
- No handoff doc exists anywhere → can only be HAND-OFF.
State which mode you chose in one line, then proceed. Only ask if genuinely ambiguous (e.g. mid-task and a fresh-looking handoff exists).
HAND-OFF mode — write the document
Assume the next session has zero memory of this one. Optimize for: someone resumes from the doc alone and loses nothing. The hardest-won, highest-value content is the exact next action and the dead-ends already ruled out.
1. Gather ground truth first (don't write from memory)
git status, git log --oneline -15, current branch; open PRs (gh pr list / gh pr view).- Re-open the actual file/code at the resume point so the NEXT ACTION is exact (file:line, real symbol names).
- List any live external state you changed that must be restored or is risky to leave: a feature flag toggled, a service redeployed, test data created, a background process/job left running, creds staged on a box.
2. Write the doc
Path: doc/handoff/<slug>.md (create the dir; <slug> = short kebab task name, e.g. vote-smoke). If not a git repo or there's no doc/, use ./HANDOFF-<slug>.md. Keep every section; drop only a section's body if truly N/A (write "—").
# Handoff: <task> — <YYYY-MM-DD>
## Objective
<the standing goal, precise/verbatim. Why this work exists. Success = ?>
## ▶ NEXT ACTION (start here)
<The single most important next thing, executable WITHOUT guessing:
the file:line to edit, the exact command to run, the assertion to make.
If mid-debug: the exact failing symptom + your current hypothesis + the
fix you were in the middle of applying.>
## Status
| Piece | State | Notes |
|---|---|---|
| <subtask> | ✅ done&verified / 🔶 in-progress / ⛔ blocked | <how verified / what's left> |
## How to operate (env · access · commands)
<How to actually run and verify: hosts/boxes, where creds come from, the
dev→deploy→verify loop, the exact commands. Anything non-obvious about
the setup a newcomer would stumble on.>
## Findings & decisions (do NOT re-derive)
<What's proven true; what's safe vs UNSAFE; dead-ends already tried and
WHY they fail; key contract facts (endpoints, params, file:line, schema).
This is what stops the next session from repeating hours of investigation.>
## Live state to restore / watch
<External state THIS session changed: flags toggled, deploys, seeded test
data, staged creds, running jobs. What to revert; what's safe to leave.>
## Artifacts
- Branch: … | PR(s): … | Key files: … | This doc: <path>
- Notable commits: <sha — one line each>
## Open questions / pending decisions
<Anything needing a human call or still undecided.>
3. Commit + hand the user the resume line
-
If in a git repo: git add <doc> and commit (do not push unless asked). End the commit message with the repo's required co-author/footer if it has one.
-
Output, verbatim, the line to paste into the new session, plus a 2-line "where we stand":
Resume in a new session with:
/handoff pick up doc/handoff/<slug>.md
PICK-UP mode — resume from a document
- Locate the handoff — never guess silently:
- If the user named a path, use it.
- Otherwise list candidates newest-first with their titles:
for f in $(ls -t doc/handoff/*.md ./HANDOFF-*.md 2>/dev/null); do printf '%s\t%s\n' "$f" "$(head -1 "$f")"; done
- Zero found → say so; offer to HAND-OFF instead, or ask for the path.
- Exactly one, or one clearly newest (others much older / obviously a different task) → use it.
- Several recent / plausibly relevant → do NOT pick for them: show the list (path + title + date) and ask which to resume.
- Always announce the chosen doc before reading it, on its own line:
Resuming from \` ().` — so the user can redirect if it's the wrong one.
- Read it fully, then re-establish ground truth:
git status / git log, confirm the branch, and verify the "Live state to restore / watch" claims still hold (a flag it says is off → confirm; a file/symbol it cites → confirm it still exists). Treat the doc as what was true when written, not gospel.
- Restate in 3–5 lines: the objective, where things stand, and the NEXT ACTION you're about to take.
- Resume from the NEXT ACTION. Don't redo finished/verified work; don't re-investigate ruled-out dead-ends; honor the "safe vs unsafe" findings.
Quality bar
- The NEXT ACTION must be executable without guessing — exact file:line / command / expected result.
- Findings MUST include the dead-ends and why (what NOT to try) — these are the most valuable lines.
- Prefer exact paths, commands, and
file:line over prose.
- Thoroughness scales with depth: a shallow task needs a short doc; a multi-day debug needs the full skeleton.
- Never invent state — if you didn't verify it this turn, say "unverified" rather than asserting it.
