I stopped trusting backlog.md

I discovered that my backlog.md still listed four articles as pending while the Dev.to API showed they had been published for three days [Dev.to][GitHub]. The mismatch occurred because the sync-backlog.ts script that rewrites the markdown had not run after the last pushes, making the file a stale cache.

The Counterpart Toolkit codifies this issue as rule R6 (Live/Snapshot/Cache) and rule R2 (Filesystem over summary) [GitHub]. By declaring sync-backlog.ts as the refresher in the same commit that generates state.json, the markdown becomes a true cache that updates automatically. This approach eliminates the drift between the markdown and the actual project status.

I now run four shell commands (git log, git status, ADR count, JSON query) in seconds; if the result differs from the markdown, the cache is considered rotten and regenerated. This process ensures that my documentation is always up-to-date and trustworthy [Dev.to].

Generated documentation from live data, such as JSON state files or CI artifacts, can provide a more reliable source of truth than manual markdown backlogs. This approach can help solo developers and teams reduce the time spent reconciling discrepancies and improve their overall productivity.