handoff ยท diff
git:20260320.999ac68 to git:20261021.55b02e6
14 added, 2 removed. Audit A to A.
---
name: handoff
- description: "Create a restart-ready handoff so a fresh agent or future turn can resume work without rereading the full conversation. Use when pausing work, ending a session, switching agents, or preparing a clean-context restart."
+ description: "Create a short-lived, restart-ready handoff so a fresh agent can resume work without rereading the full conversation, and delete it once read. Use when pausing work, ending a session, switching agents, preparing a clean-context restart, or finding a handoff addressed to you."
---
# Handoff
+ ## A Handoff Is Temporary
+
+ - The project notebook or log is the running record. Do not keep a standing handoff file beside it
+ and update it as a second status page: the two drift, and a stale handoff misleads the next agent
+ more than having none.
+ - Write a handoff only at an actual hand-off, when another agent or a fresh session takes over.
+ It points into the notebook; it does not replace it.
+ - The receiving agent reads its handoff, confirms the notebook holds everything durable in it, moves
+ anything missing into the notebook, and then deletes the handoff.
+ - An agent that finds an old handoff for its own lane treats it the same way: check, fold into the
+ notebook, delete.
+
## Optimize For Cold Restarts
- A handoff is for a fresh agent with no working memory.
- The goal is fast re-entry, not a narrative recap.
- - Update the canonical notebook or log first if the project already has one. Then write the handoff.
+ - Update the canonical notebook or log first if the project already has one. Then write the handoff, and expect it to be deleted once read.
- Compose this skill with domain skills such as `$lab-notebook`, `$job-babysitting`, or `$slurm`.
## Use This Contract
Every handoff should answer:
1. Goal:
- what problem or decision is in flight.
2. Current state:
- what is true now.
3. Evidence:
- exact paths, job IDs, branches, commits, configs, logs, or artifacts that support the current read.
4. Open uncertainty:
- what is still unclear, blocked, or waiting.
5. Next action:
- the exact next check, command, or edit that should happen first.
## Make The Handoff Restartable
- Include exact file paths and identifiers, not vague references such as "the latest run" or "that config".
- Separate facts from hypotheses.
- Name what has already been ruled out so the next agent does not repeat dead work.
- If code changed, include branch, commit SHA if any, validation status, and whether the worktree is dirty.
- If jobs are involved, include job IDs, current state, run root, and the next decision point.
- If waiting on an external event, say what event should trigger the next step.
- End with one concrete re-entry action.
## Keep It Short
- Default target: 5-12 lines or a very short bullet list.
- Prefer one crisp sentence per field over a long paragraph.
- If the handoff is getting long, move durable detail into the project notebook and keep the handoff as an index into that evidence.
## Avoid Weak Handoffs
- Do not retell the whole chronology.
- Do not say "continue from here" without naming the first command or check.
- Do not omit the current best explanation.
- Do not omit validation status after code changes.
- Do not hide uncertainty behind generic phrases such as "needs more debugging".
## Restart Test
- A good handoff lets a fresh agent resume within a couple of minutes using only:
- the handoff,
- the repository,
- the referenced notebooks, logs, and artifacts.
- If that would still require rereading the full chat, the handoff is incomplete.
## References
- Read `references/templates.md` for compact templates for code work, experiments, and job-monitoring handoffs.