There is no TODO

On Friday, August 28, 2026, I deleted a directory called TODO. Well, obviously I didn't delete it myself. I asked an agent to.

It held 22 items, each one a small Markdown file describing something the system ought to do and didn't, or did and shouldn't. They were good items, carefully written and graded by severity from S1 down to S4. And every single one of them was in the wrong place.

The 22 items now live in the nine documents that describe the capabilities they were about. The directory is gone. In its place is a test that fails the build if anyone creates a new one, or starts a comment in any source file with TODO, FIXME, HACK or XXX.

That was the small backlog. The big one was in Asana: more than 200 tasks, rotting away, with nobody reading them and nobody updating them. Most of them were out of date, of course, the way backlogs always are. One asked for a document to be updated with the details of a production issue. The document had since been rewritten from scratch, and the production system decommissioned. Tickets have a half-life. Nobody has ever measured it, because measuring it would mean reading the tickets.

Deleting the folder is the whole method in miniature. The Asana tasks are the whole problem, and not in miniature.

Knowledge-driven development is an experiment. I started it that Friday in August, and it isn't battle-tested yet. This series describes what I'm doing and why.

---

1. The backlog is a second map

Every software team I've worked with has kept two descriptions of the system. One is the system itself, plus whatever documentation survived contact with it. The other is the backlog: tickets, epics, stories, a board with columns. The first describes what is. The second describes what should be, minus what is, as of whenever someone last updated it.

These are two maps of the same territory, drawn by different people, for different readers, in different tools, and updated by different acts. Changing the code is one act. Closing the ticket is another. Only one of them is enforced by anything, and it isn't the ticket.

So the maps drift. A ticket says a thing is broken that was fixed three sprints ago. A feature exists that no ticket ever mentioned, because someone built it on a Friday. The board says 80% done and the system says otherwise. The map is not the territory, and the backlog is a second map, drawn from memory, of the first one.

And the people drawing it are trying to look good and justify their paychecks.

Two descriptions updated by two acts will diverge, however disciplined the people updating them are, and a description kept by the people it's used to judge will flatter them. The usual cure is more discipline anyway: grooming sessions, ticket hygiene, a definition of done that includes closing the ticket. Every team that has ever run a ticket tracker has paid for that, usually in meetings.

Processes that aren't valued by the people who have to put in the effort feel like imprisonment. The prisoners escape, and the guards are left humiliated and confused.

There's a scene in The Matrix where a child bends a spoon just by looking at it, then tells Neo not to try bending it himself, because that's impossible. Instead, he should realize the truth: "There is no spoon."

The backlog is the spoon.

2. The backlog is a queue for hands you don't have

Drift is the first problem with a backlog. The second is that it no longer has a reason to exist.

A backlog, and the sprint planning built on top of it, is a tool for managing work that isn't being done because there are no hands and brains to do it. Sometimes for years. The work waits in a queue, and every two weeks somebody grooms the queue.

An agent can finish that work as fast as a developer can guide it and feed it tokens. In my case, the limiting factor should be the developer. It isn't, because my organization doesn't feed me enough tokens for that to be true. Organizations are comfortable paying salaries to add hands. They're not comfortable paying for tools that multiply those hands at a lower cost.

Still, hands and brains were the bottleneck the backlog was built to manage, and they aren't any more. The bottleneck now is a line in a budget. Nobody has told the backlog.

Given a serious development team, the backlog is pointless.

So are the planning rituals around it. The entire design of a major new system could be implemented before the planning-and-cost-assessment phase is over. Building the thing is now faster than estimating it, which turns the cost assessment into a historical document. The result can be reviewed in a real environment, and adjusted to meet the stakeholders' needs in the next phase.

What that takes is a description of what the system is meant to be, and an account of how much of it is true yet.

3. Knowledge-driven development is one map

Knowledge-driven development removes the second description. What's left is one description, and it's the spec: everything the system wants to be in its absolute end state, as far as anyone currently knows it. It's written in the present tense, as if all of it were already true, and every statement carries a mark saying whether it is yet. A ⚠️ paragraph marks the gap between what the system should do by design and what has been built so far, written in the voice of the person who will use it, in the place they'll look for it. A ❌ paragraph is a bug report, in the place the bug will be found. A ✅ paragraph is a claim someone has verified, and the only kind you're allowed to build on.

The description is split by audience, not by tool. The product owner gets the feature documents. The operator gets the operator's manual. The integrator gets the API contract. The maintainer gets all of those, plus the architecture: the things that really should be documented about a system. A class tree isn't one of them. Any IDE will draw you one of those out of the box.

The specification, the backlog, the release notes and the onboarding material are the same set of facts, filtered for different readers. They always were. We just kept them in four places and paid four times to keep them roughly in sync, which we didn't.

When I want to know every known bug in the system, I don't open a board. I ask Claude, and Claude runs this:

grep -rn '❌' documentation/

And when I want to know what's left to build:

grep -rn '⚠️' documentation/

That's the closest thing I have to a backlog, and it's a grep. It can't drift from the documentation, because it is the documentation. Nothing on it is waiting for hands, either. It gets shorter as fast as I'm allowed to feed the agents tokens.

I call it knowledge-driven development on purpose. "Documentation" makes people think of the thing written after the code, by nobody, read by nobody, and out of date before the pull request merges. These documents are written before the code, read on every change, and they're the only description of the system that's allowed to exist. They're what the system knows about itself, including what it knows it can't do yet.

4. Files beat tickets

Agents don't read tickets. Not unless you ask them to, and even then a ticket is a poor way of communicating with one. Files are better.

An agent's context is loaded from files. The implementing agents work from the documents the planner wrote, and the repository's agent instructions tell every agent to read the documents about whatever it's changing. A ⚠️ in the document about the capability being changed gets read whether anyone remembers it or not. A ticket about the same capability gets read when somebody remembers it exists, finds it, and points the agent at it, and what the agent gets then is a description written for a planning meeting, about code that may have changed since. Putting the requirement where the agent will read it is the difference between a rule that applies and a rule that applies when somebody remembers it.

For a human team, a ticket tracker is a tolerable bad idea. Humans don't really remember the ticket they read on Monday when they're editing the file on Thursday, but they can usually find it again, and they can claim they're working on it. What they find is rarely worth the search. In most teams, a human-written ticket is very often nothing but a subject line, or a single paragraph if you're lucky. It doesn't, in any form or fashion, convey the intent and context needed to resolve it correctly.

Most TODO items and most tickets are of no interest to most of the organization anyway. A ticket tracker is a road atlas of the entire country, kept in another building, where every reader cares about one page and it's a different page for each of them. A ⚠️ in the document the agent is reading is a sign on the corner where you're standing.

Agents write nearly all of my code and nearly all of my tests. They read the signs every time, because the signs are in the documents they read before they work. They'd read the atlas too, if I sent them to the other building.

I don't.

---

There is no separate backlog. The 22 items that used to sit in a folder called TODO are now sentences in the documents that describe what they're about, each one marked, each one findable by grep, each one in the place an agent will read it at the moment it matters. So are the TODO comments that used to be scattered through the source files, each one moved into the document that owns the code it sat in. Whatever wisdom the Asana tasks contained has been distilled and stored in the repository as well. (Same caveat.) The tasks that were too detailed for Asana are gone from it. What's left there are the major work items, and each one refers to the document that describes it.

My agents do still visit the other building now and then, to update Asana for the project managers and product owners who live there. I hear it's lovely this time of year. They go there to write, not to read. Asana is still a second map. It's just not the one the code is built from.

The rest of this series is how that works in practice: the marks, how I run a feature through them, what they replace, and where they break.

The folder is gone, and the build will fail if it comes back.

There is no TODO.