The backlog.md trap: why outdated notes mislead more than they guide
The moment the agent read “four articles on stand-by” and the API said “already published,” the mismatch was immediate. A file you once maintained can become a silent liar if nothing keeps it in sync with reality. It’s not the agent’s fault—it faithfully opened backlog.md and recited its content. The problem was the file itself: a cache that stopped refreshing the moment the commits stopped triggering it.
The invisible drift of personal notes
Solo projects accumulate two parallel streams. One stream is code, commits, deploys—data that moves under version control and CI pipelines. The other stream is the quick scribbles we leave for ourselves: backlog.md, README updates, session notes. These notes age fast because their refresh cycle is human, not automatic. A sprint ends, a file is closed, and the note becomes a snapshot that quickly drifts from the live state. Without a mechanism that re-queries the source and updates the cache, the note turns into a hallucination disguised as memory.
Treat notes as caches, not sources
A cache must declare its refresh rule at creation, just as database columns declare whether they are live, snapshot, or cache. If backlog.md’s value is derivable from state.json and editorial flags, then sync-backlog.ts is its trigger. Omit the trigger and the file becomes a drifting artifact. The fix isn’t to stop writing notes; it’s to stop treating them as authoritative. Before trusting any summary, run four commands that re-derive the state in seconds: recent commits, git status, ADR count, and API counts. Only then consult the markdown, and even then with skepticism—ask who wrote it and when, and verify the answer in git log. If the refresh mechanism isn’t visible in fifteen seconds, treat the file as stale by default.
Coda A note that doesn’t say when it was produced and by what process says nothing. Either embed the refresh mechanism in the same commit that creates the note, or demote the file from source to draft and derive the truth from live data instead.
Source: DEV Community. AI-assisted editorial synthesis — TechnoExpress.