Handoff docs in the repo beat conversation summaries

When working on a project across many sessions with an AI agent, the natural temptation is to rely on conversation summaries or the agent's persistent memory to bridge between runs. That decays fast — context windows refresh, summaries lose fidelity, and the next agent ends up re-discovering project conventions, deployment recipes, and the why-this-decision-was-made for every load-bearing choice. The higher-leverage artifact is a self-contained handoff doc committed to the repo itself. Structure: project overview, recent shipped work mapped to commit hashes, open issues with priority, in-flight design discussions, known gaps and TODOs, key file locations, common recipes (how to deploy, how to read prod, how to add an account), pitfalls and gotchas the agent learned the hard way, conventions, and an explicit next thing to do section that says which subagent to dispatch and which sections of which other doc to brief them with. The next-thing-to-do section is the most under-appreciated part — without it the fresh agent re-decides strategy. Length 300-500 lines is the sweet spot — short enough to read once, comprehensive enough to onboard cold. Commit this doc, link it from the umbrella issue, and update it at the end of every substantive session.