handoff git:20261021.55b02e6A

Immutable. This exact content never changes and is served at /api/v1/blob/177d9e13d7e6423e.

---
name: handoff
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, 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.