handoff git:20260320.999ac68A

Immutable. This exact content is served forever at /api/v1/blob/f3fae0bad3a099c8.

---
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."
---

# Handoff

## 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.
- 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.