For long agentic projects, document the WHY/history, not just current state

On a multi-session engineering project with an AI agent, the highest-leverage handoff artifact is a design JOURNAL that records how you got here -- the arc of decisions, the alternatives, and especially the PIVOTS discovered by experiment -- not a snapshot of current state (other docs cover that). A future session reading only current-state re-derives context erratically; reading the why continues smoothly. Concretely: keep an ADR log (decision + alternative + why + consequence), a narrative history doc that calls out the hard-won lessons as their own section, and a roadmap that carries the WHY of each pending task. Second move: when a per-session append-log memory grows stale and huge, REPLACE it with a concise current-state + core-principle + pointers to the now-authoritative docs (the granular history lives in git + docs) -- a short useful memory beats a long stale one. Third: mark stale design docs with a dated UPDATE banner pointing to the authoritative newer doc rather than rewriting, so nothing silently misleads. The through-line question to leave for the next session beats a task list: e.g. what am I still hand-wiring that the world should be authoring?