{"slug": "why-i-stopped-reading-my-own-backlog-md-and-what-i-read-instead", "title": "Why I stopped reading my own backlog.md (and what I read instead)", "summary": "A developer discovered that their AI agent was providing inaccurate status reports because the underlying backlog.md file was not being updated. The agent faithfully read the stale file, leading to a mismatch between the reported and actual state of published articles. This incident prompted the developer to formalize rules in their Counterpart Toolkit, requiring that any summary file declare its refresh mechanism and that filesystem commands take precedence over written summaries.", "body_md": "Wednesday, May 21, start of session, coffee next to the keyboard. I ask the agent where we stand on the DEV.to series. Clean answer, articulated, *\"Four articles on stand-by, ready to publish.\"* I reread. Half a second of unease, because I think I saw two or three of them go through DEV.to last week, but I slept in between and I'm no longer sure. I type the question that changes everything, *\"Are you sure articles remain to publish?\"* The agent re-queries the DEV.to API in parallel, opens `scripts/devto/state.json`\n\n, crosses the two. The four articles have been published for two or three days.\n\nWhat I just read wasn't a hallucination. The agent did exactly what was expected of it, namely open `articles/backlog.md`\n\n, read the table, restitute what it said. I'm the one who had stopped updating that file. `sync-backlog.ts`\n\nhadn't run after the pushes of last week. The markdown said *\"stand-by\"* while production said *\"published\"*. The typist didn't lie. She read faithfully a file I had written myself and that I was treating as authority while nothing was maintaining it.\n\nThis is the most common failure mode of a solo project that lasts. Each day produces two flows. On one side the matter that moves, made of commits, deploys, rows in the database, statuses that transition. On the other side the writings we draft to keep our bearings, namely `backlog.md`\n\n, the root `MEMORY.md`\n\n, the Sunday-night session note, the README of the folder we refactored last week. These writings are produced quickly, in the gesture that closes a sprint, and they are maintained slowly, or not at all, because nothing in the pipeline triggers to close them.\n\nR6 of the Counterpart Toolkit says it for SQL columns, *Live / Snapshot / Cache mandatory*. Any column derivable from other data must declare its category in the commit that creates it. If it's a Cache, the refresher mechanism (`GENERATED ALWAYS AS`\n\n, SQL trigger, materialized view with planned REFRESH) ships in the same commit. No category declared, no commit.\n\n`backlog.md`\n\nis exactly the same logical object. Its value is derivable from `state.json`\n\nplus a few editorial constants. `sync-backlog.ts`\n\nis its applicative trigger. Without a call, the Cache drifts.\n\nR2, *Filesystem over summary*, codifies the gesture since May 15. Before any status report, four shell commands, in this order. The markdown comes last, and it comes as draft thinking, never as a source.\n\n```\ngit log --since='7d' --oneline\ngit status --porcelain\nls docs/adr/ | wc -l\ncat scripts/devto/state.json | jq 'to_entries|map(select(.value.published))|length'\n```\n\nThe result reads in three seconds. If something surprises me, a commit I had forgotten or one more ADR than memory expected, I dig there, not in `backlog.md`\n\n. When I do read the markdown, I read it with the implicit question *\"who updated it, when\"*, and if the answer doesn't come out of `git log`\n\nin fifteen seconds, I treat it as rotten Cache.\n\nA summary that doesn't say when it was produced, and by what mechanism, says nothing. Either you declare its refresher in the commit that creates it, be it a script, a trigger, a cron, and it lives as a managed Cache, or you stop treating it as a source and it goes back to being a draft. R6 says the rule for the database. R2 says the same rule for the writings you address to yourself. An agent that opens `backlog.md`\n\nbefore `git log`\n\nis not a bad agent, it's an agent that faithfully executes a human gesture that should have been forbidden upstream. The morning of May 21, it wasn't the agent that lied to me, it was my own typist who, the night before, hadn't closed the note.\n\n*Counterpart Toolkit v0.7, rule R2 — Filesystem over summary. Extracted from R1 in v0.4.1, promoted in its own right. Current version of the toolkit lives in CC-BY-4.0 on github.com/michelfaure/doctrine-counterpart.*", "url": "https://wpnews.pro/news/why-i-stopped-reading-my-own-backlog-md-and-what-i-read-instead", "canonical_source": "https://dev.to/michelfaure/why-i-stopped-reading-my-own-backlogmd-and-what-i-read-instead-3gke", "published_at": "2026-06-19 15:48:22+00:00", "updated_at": "2026-06-19 16:07:31.577352+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "large-language-models"], "entities": ["DEV.to", "Counterpart Toolkit", "Michel Faure", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/why-i-stopped-reading-my-own-backlog-md-and-what-i-read-instead", "markdown": "https://wpnews.pro/news/why-i-stopped-reading-my-own-backlog-md-and-what-i-read-instead.md", "text": "https://wpnews.pro/news/why-i-stopped-reading-my-own-backlog-md-and-what-i-read-instead.txt", "jsonld": "https://wpnews.pro/news/why-i-stopped-reading-my-own-backlog-md-and-what-i-read-instead.jsonld"}}