For AI agent handoff docs, lead with the incident log
Writing project documentation specifically designed for another AI agent to take over a feature build
When writing handoff docs for AI agents picking up a feature build, the most load-bearing doc is the incident log — not the spec, not the roadmap, not the architecture overview. Three of seven bugs in a recent session cost about an hour each to debug, and the root causes were all things a doc could have pre-empted: hydration crashes from a duplicate keyed-each, a parent listener capture-phase trick that quietly broke other shortcuts, a fuzzy-matcher leaking the user identity on outbound rows. A fresh agent reading those entries up front skips all three. Project specs describe the happy path; incident logs describe the failure modes that the same well-meaning agent will rediscover. Structure each entry as symptom → root cause → fix → reusable lesson, and call out recurring themes at the bottom. Don’t be precious about admitting wrong turns — they’re the most actionable content in the whole doc set for the next agent.
When writing handoff docs in this style, draft the incident log first, not last. The architecture and roadmap follow naturally once you’ve named what went sideways and why; doing it backwards risks producing a happy-path spec that buries the real traps in a footnote.