handoff

Agent Handoff

Purpose

Write a handoff document: a single, self-contained briefing that lets a fresh agent take over an in-progress task with zero loss of context. The successor agent reads the handoff, then reads everything the handoff points it to, and ends up understanding everything the current agent understands — the goal, the history, the reasoning, the dead ends, and the next steps.

This skill produces the handoff in chat unless the user asks to save it to a file.

The handoff is NOT a status update. It is a context-transfer instrument. Its success criterion: a fresh agent that has read only the handoff plus the files/chat sections it names can continue the work without re-asking questions the current agent already answered.

---

The Two Hard Problems This Skill Solves

1. Lazy reading. Successor agents skim. They read the first 100 lines of a 2000-line file, assume they understand it, and produce wrong work. The handoff MUST force full reads (see "The Full-Read Mandate" below). This is non-negotiable and must appear prominently in every handoff you write.

2. Lossy history. A long session contains essential decisions tangled with abandoned threads. The successor needs the outcome and rationale of abandoned threads (so it does not re-propose them or contradict them) but NOT their full blow-by-blow detail. The handoff must compress abandoned threads to "what was tried, why it was dropped" while preserving live threads in full (see "Compressing History" below).

---

The Full-Read Mandate (Include This Verbatim in Every Handoff)

Every handoff you write MUST contain a block instructing the successor to read in full. Reproduce this block near the top of the handoff, adapted to the project:

READ DISCIPLINE — NON-NEGOTIABLE. You must read every file listed in the "Files to Read" section IN FULL before writing anything. "In full" means: call the Read tool with limit: 2000 (or higher if the file exceeds 2000 lines — check line count first with wc -l and read in 2000-line pages until you reach the end). Do NOT read partial files. Do NOT assume you understand a file from its name, its first screen, or a grep hit. If a file is 1800 lines, you read all 1800. If it is 3500 lines, you read it in two passes. You are not permitted to begin the task until every listed file has been read end to end. Reading is cheap; producing wrong work from a half-read file is expensive.