Context handoff

context-handoff — Survive a context reset without losing the thread

Purpose

Long autonomous work outlives a single context window. When the window fills (or a session ends), everything not written down is lost — and the next session re-derives it badly or not at all. This skill captures the minimum sufficient state to resume cleanly: not a transcript dump, but the working set a fresh agent needs to pick up exactly where this one left off.

When to trigger

• The agent is nearing its context limit mid-task (don't wait for the panic — hand off early).
• A session is ending with work in progress.
• Handing a task from one agent/person to another.

How to run

1. Capture only the working set — what's needed to continue, not a history of what happened.
2. Write to a durable location: ./.handoff/<task-slug>.md (or a memory key the user names).
3. Make the next step unambiguous. The single most important field is "NEXT ACTION" — the very next concrete thing the resuming agent should do.
4. Point to evidence, don't inline it — file paths, line numbers, command outputs by reference.

The handoff template

# Handoff: <task>

## Goal (unchanged)
<the original objective, one or two lines>

## NEXT ACTION  ← start here
<the single concrete next step, specific enough to execute without re-reading everything>

## State / progress
- Done: <what's verified complete — with evidence: passing cmd, committed sha, rendered screen>
- In progress: <what's half-done, and exactly where it stands>
- Not started: <remaining scope>

## Key decisions & constraints
- <decisions already made and why — so they aren't relitigated>
- <hard constraints that must hold>

## Landmines / open questions
- <what bit me, what's fragile, what's still unresolved>

## Map (where things are)
- <file:line pointers, relevant commands, the 2–3 files that matter>

Principles

• Resumability over completeness. A short doc that lets the next agent act beats a long one that buries the next action.
• Evidence by reference. Link to the passing command / commit / file:line; don't paste logs.
• Decisions are state too. Record why, so the resuming agent doesn't reopen settled questions.
• Hand off early. A clean save at 70% context beats a panicked one at 95%.

Notes

• If a .handoff/ for this task already exists, update it in place — keep one current handoff per task, not a pile of stale ones.
• Pairs with the context-handoff trigger inside failure-mode-audit mode #3 (context anxiety): the handoff is the mechanism that turns "nearing the limit" into a clean checkpoint, not a rush.