Why manual backlogs fail solo devs—and what to track instead

The morning of May 21 began like any other for the developer, coffee in hand and an AI assistant ready to summarize their work. When asked about pending articles for the DEV.to series, the agent confidently reported four pieces "on stand-by." A quick mental check revealed a discrepancy—those articles had already gone live days earlier. The realization hit hard: the markdown file hadn't been updated since the last deploy, rendering it worse than useless. It actively misled.

The danger of static summaries in fast-moving projects

Solo developers often rely on summary files like backlog.md to track progress. These documents start as accurate reflections of work but degrade over time because they aren’t part of the project’s live data pipeline. Each commit, deploy, or status change moves the actual state forward, while the summary remains frozen in time. The developer’s script that once synchronized the two files (sync-backlog.ts) hadn’t run in days, leaving the markdown out of sync with reality. What was meant to be a source of truth had become a cache without a refresher—a classic failure mode in long-running projects.

How to make documentation track the truth

The solution came in the form of a simple rule: filesystem over summary. Before trusting any written account of progress, the developer now runs a series of commands that query the live system directly:

• git log --since='7d' --oneline to review recent commits
• git status --porcelain to check uncommitted changes
• ls docs/adr/ | wc -l to count architecture decision records
• cat scripts/devto/state.json | jq 'to_entries|map(select(.value.published))|length' to fetch published articles

These commands take seconds to execute and return data that hasn’t been manually curated. If something unexpected appears—like an extra commit or an unaccounted ADR—the developer drills down into the raw system, not the summary file. The markdown becomes a draft again, meant to be read critically with the question: Who updated this, and when? If the answer can’t come from a git log query within fifteen seconds, the file is treated as obsolete.

The philosophy behind the fix

This approach isn’t just about tools; it’s about discipline. A summary that doesn’t declare its refresh mechanism is unreliable by design. The developer’s Counterpart Toolkit formalizes this with Rule R6 for databases: Any column derivable from other data must declare its category and include a refresher mechanism in the same commit. The same logic applies to documentation. Whether it’s a backlog.md, a README, or a session note, if it’s meant to reflect the current state, it must be part of the automated pipeline.

An AI agent that reads backlog.md before checking git log isn’t flawed—it’s faithfully executing a broken process. The real issue lies upstream, where manual updates were allowed to persist without triggers or validations. By shifting the source of truth back to the filesystem and its version-controlled state, solo developers can avoid the cognitive load of maintaining parallel universes of truth—one in their head, one in a text file, and one in the codebase.