---
name: "context_handoffs"
description: "How to hand context between agents or sessions. Use when a session is getting long, when work resumes after a pause, when one agent hands work to another, or when someone asks what the next agent needs to keep going."
metadata: { "includeInPrompt": true }
---

# Context Handoffs

## Purpose

Raw transcripts cost too much context and bury the decisions that matter. Bare summaries lose too much and force rework. A good handoff keeps decisions and their reasons, hard constraints, quirks found, open or blocked state, and pointers to evidence, and drops everything else. The next agent should be able to act without reading the old transcript.

## Workflow

### 1. What to keep

- Decisions made and why. A decision without its reason gets re-debated later.
- Hard constraints and don'ts: things that must not happen again, live blockers, approval gates.
- Tool quirks discovered: anything a fresh agent would trip on if it did not know.
- Open and blocked state: what is mid-flight, what is stuck, what is waiting on whom.
- Pointers to files or evidence: paths, ids, timestamps. Pointers, not pasted content.

### 2. What to drop

- Exploration dead ends that changed nothing.
- Raw logs and intermediate drafts, unless one contains the only copy of a key result.
- Small talk, thinking-out-loud, and anything already saved in a file the next agent can read.
- Anything already captured in durable notes. If it is in a file, point at the file.

### 3. Session briefing format (agent-to-agent delegation)

Use this when one agent delegates to another. Fill every field; leave nothing to inference.

```
BRIEFING
Goal: One sentence. The exact outcome requested.
Scope: What is in bounds. What is explicitly out of bounds.
Constraints: Hard don'ts, approval gates, budget or time limits.
Background: The minimum the next agent needs. Link files, not logs.
Decisions already made: Each with its reason in one line.
Evidence pointers: File paths, record ids, timestamps, URLs.
Quirks: Tool or environment gotchas that would waste time to rediscover.
What done looks like: Concrete, checkable. How the result gets verified.
```

### 4. Checkpoint format (pause and resume)

Use this when a session stops and will resume later, with the same or a different agent.

```
CHECKPOINT
Session id / date:
State: What was accomplished, in bullets. Each item marked verified or claim.
Next step: The single next action, specific enough to run immediately.
Open questions: Blocking questions with who must answer them.
Verification checklist: How to confirm the resumed work is correct before moving on.
Pointers: Files, artifacts, logs that matter. Nothing pasted inline.
Do not redo: Work that is already done and how to confirm it from the pointers.
```

### 5. The handoff check

Read the finished handoff and ask: could a fresh agent act on this without reading the old transcript? If the answer is no, find the missing piece and add it. Common gaps: the reason behind a decision, the exact next step, where the evidence lives. When the check passes, the handoff is done.

## Output Contract

A good handoff document contains:

- A goal line and a scope line, so the next agent knows what to do and what not to touch.
- Decisions with reasons, constraints, quirks, and open or blocked state.
- Evidence as pointers, never pasted dumps.
- A checkable definition of done or, for checkpoints, a verification checklist.

Test it with the fresh-agent test: hand the document to an agent with no prior context and see whether it can start work without asking for the transcript. If it asks for the transcript, the handoff failed.

## Operating Rules

- Pointers beat pasted logs. A path and an id cost less than a dump and stay fresh longer.
- Every decision carries its reason. A reasonless decision will be re-debated.
- Mark what is verified and what is a claim. Never present an unconfirmed result as fact.
- Never put credentials, secrets, tokens, or private keys in a handoff document. If the next agent needs access, describe how it is provisioned through the normal flow, do not include the value.
- Keep it short. Reading the handoff should cost less than redoing the work. If it grows past one screen, cut chatter and keep fields.
- Drop dead ends completely. If an exploration changed nothing, it does not belong in the handoff.
- Do not reference files that only exist in your own session. Everything the next agent needs is inline in the handoff or pointed at with a durable path it can actually read.