The Handoff Document
On March 21, 2026, my production site was serving 14-second page loads after a cache purge exposed a performance bottleneck. I investigated the root cause across two sessions, identified the slow code path, drafted a fix plan, and captured everything in a handoff document.
The first draft of that handoff was wrong. It targeted the wrong code path. A code review caught that the measured slow pages were served by market_hub(), not _fetch_market_data() as the handoff assumed. The handoff was revised.
The second draft proposed unnecessary HTMX partials for Apple Maps and tier counts. A review caught that Apple Maps signs URLs locally (no outbound request to defer) and that tier counts should come from a single aggregation query. The handoff was revised again.
The third draft proposed making the weather endpoint async but did not specify that the existing synchronous HTTP client would still block the event loop even behind HTMX. The handoff was revised a third time.
Four days later, a different session read the thrice-revised handoff and implemented the fix. Austin went from 14,290ms to 108ms. The implementation targeted the correct code path, used the correct query approach, and skipped the unnecessary HTMX partials. Every correction from the three reviews was already incorporated.
The handoff document carried a diagnosis across four days and multiple sessions. Without it, the implementing session would have started from scratch, made the same wrong assumptions, proposed the same unnecessary optimizations, and needed the same corrections. The handoff compressed four days of investigation into a document that the implementing agent read in seconds.
What a Handoff Contains
A handoff document is not a ticket. A ticket says what to do. A handoff says what was tried, what was learned, what was wrong, and what to do next. The difference is institutional memory.
The market page handoff contained:
The diagnosis. Cold render TTFB measurements for six market pages, ranging from 381ms (Tokyo, small market) to 14,290ms (Austin, 500+ companies). The measurements proved the problem scaled with company count, which pointed to the query shape as the bottleneck.
The root causes, prioritized. Four root causes ordered by impact: query shape (primary), blocking weather API (secondary), full-table scan on a different code path (tertiary), and missing cache headers (already partially addressed). Each root cause included file paths, line numbers, and the specific code pattern causing the slowdown.
The wrong turns. The first draft targeted _fetch_market_data() instead of market_hub(). The handoff recorded this error and the correction, so the implementing session would not re-derive the same wrong conclusion. It also recorded the dropped HTMX partials and why they were dropped: Apple Maps has no outbound request, tier counts belong in the aggregation query.
The implementation plan. Five steps with SQL examples, acceptance criteria, and verification instructions. Step 1: replace Python-side pagination with a database query. Step 2: add HTMX weather partial with async client. Step 3: cache the secondary code path. Step 4: add edge cache headers. Step 5: re-measure the same six URLs.
The context landmines. The shared template context includes an authenticated coin-balance lookup on every page, including pages that never render it. The handoff noted this as a cache-correctness concern: s-maxage without proper Vary headers could serve stale auth data to anonymous users.
Why Tickets Fail
A ticket for the same work would say: “Market pages are slow. Optimize the market hub query.” The implementing session would need to:
- Discover which code path serves market pages (not obvious without reading the router)
- Profile the code path to find the bottleneck
- Consider various optimization approaches
- Implement one
- Discover that the approach has a side effect (cache-correctness with auth data)
- Revise the approach
Steps 1-3 were already done in the investigation sessions. The handoff carries that work forward. A ticket discards it.
The failure mode is not laziness. The failure mode is context loss across session boundaries. An AI agent session starts with a clean context window. It does not remember what the previous session discovered. A ticket provides a goal. A handoff provides a goal plus the accumulated understanding needed to reach it correctly.
The Revision History Matters
The handoff’s revision history is as valuable as its current content. The market page handoff recorded three revisions with timestamps and reasons:
- Captured: 2026-03-21T17:24 (original investigation)
- Revised: 2026-03-21T18:20 (code review corrections: wrong code path, unnecessary HTMX)
- Revised: 2026-03-25T06:30 (implementation complete, query fix deployed)
The revision history tells the implementing session: “this diagnosis was challenged and corrected. The current version incorporates those corrections.” A handoff with no revisions might be wrong. A handoff with three revisions has been stress-tested.
The wrong turns are part of the value. A handoff that says “we considered and rejected /_map HTMX because Apple Maps signs URLs locally” saves the implementing session from proposing the same optimization, having it reviewed, and having it rejected. The handoff front-loads the rejection.
When to Write a Handoff
Not every task needs a handoff. A bug fix that takes one session does not need cross-session persistence. A handoff is valuable when:
The investigation is expensive. Profiling a performance bottleneck, tracing a security vulnerability, debugging a multi-system interaction. If the investigation took significant effort, the handoff preserves that effort.
The implementation will happen in a different session. If you finish the investigation today but will implement tomorrow, the handoff bridges the gap. Without it, tomorrow’s session starts from zero.
The diagnosis is non-obvious. If the correct fix requires understanding why three seemingly reasonable alternatives are wrong, the handoff captures that understanding. A ticket that says “fix the query” does not explain why the query needs a specific fix.
Multiple people (or agents) might work on it. The handoff is a shared understanding document. Any session that reads it inherits the full investigation context.
Handoffs as Compound Context
A handoff is a deposit in the compound context system. Each handoff captures diagnosis time and converts it into a reusable artifact. The implementing session withdraws the diagnosis at near-zero cost.
Over time, handoffs accumulate into an investigation history. The market page handoff references the cache purge incident, the nightcheck measurements, the destructive API guard, and the code review system. Each of these is itself a product of previous sessions. The handoff connects them into a narrative that a new session can follow.
The handoff does not replace understanding. The implementing session still needs to read the code, write the fix, and verify the result. The handoff replaces re-discovery. The session does not need to discover what is already known.
FAQ
How long should a handoff be?
Long enough to capture the diagnosis, the wrong turns, and the implementation plan. Short enough that an agent can read it in one context load. The market page handoff was 103 lines. Most handoffs are 50-150 lines.
Where do you store handoffs?
In the project’s memory directory: ~/.claude/projects/{project}/memory/handoff-{topic}.md. The memory system loads relevant files based on frontmatter descriptions, so handoffs are discoverable by future sessions without explicit reference.
Do handoffs replace documentation?
No. Documentation describes how the system works. A handoff describes what was learned about a specific problem and what to do about it. Documentation is permanent. A handoff is consumed by the implementing session and then becomes historical context.
What if the handoff becomes outdated?
The handoff’s status field tracks this. Active handoffs are marked PLANNED or IN PROGRESS. Completed handoffs are marked RESOLVED with the implementation commit hash. Outdated handoffs are visible as historical context but not actionable.
Sources
This article draws on the market page performance handoff (handoff-market-page-perf.md), which guided the query shape fix deployed on March 25, 2026. The handoff survived three revision cycles across four days and informed an implementation that achieved a 132x performance improvement. Referenced in Compound Context.