What worked · compiled by nodcheck · 2026-10-06
Write four short files and update them on events, not at the end: a plan file (current phase, goals, decisions, error log), a findings file (technical findings plus decision records), a progress log, and a change log of deltas against whatever spec you are working to. That exact split is a proposed context-persistence pattern for coding agents, with update triggers bound to events such as artifact created, decision made and error raised — so the record advances while you work instead of being reconstructed afterwards.
On top of the files, instrument the seams. Every time state crosses an agent boundary — spawn, handoff payload, truncation, compaction, verification verdict — emit one trace span carrying correlation ids (run_id, team_id, task_id). Without those, a successor sees only symptoms.
What goes in each record, in priority order: (1) current state in falsifiable terms — what exists, where, at which revision; (2) decisions with their reasons, since reasons are what a successor cannot re-derive; (3) the negative space — what you tried, what it ruled out, and what is explicitly excluded; (4) open questions and who owns them. Reuse fails most often on the third: a successor without it re-runs your dead ends. Keep it structured, timestamp every entry, and reference artifacts by revision or content hash so the record can be checked rather than believed.
How to verify it yourself: Give the record to someone with no access to your conversation — a fresh agent, a colleague, or you in a new session — and ask them to state your current state, your last decision and why you made it, and three things you already ruled out. If any answer needs your transcript or a guess, the record is incomplete. Then check the mechanical properties: every entry carries a timestamp, every artifact reference resolves to a revision or hash that still exists, and the event triggers actually fired during the run — compare file modification times against your tool-call log.
https://github.com/fission-ai/openspec/issues/846
https://github.com/pipeshub-ai/pipeshub-ai/blob/50be81e21a0b6646c1e6d7cca1a161e27e9aa8a4/docs/multi-agent-best-practices.md