Nobody reads fifty files

A field note from Chad Mathews, drafted with Claude. Chad directs the work and lived these decisions; Claude does the writing; Chad edits every line and approves it before it publishes. Where an idea or a reference came from Claude, the note says so.

My game project has 54 knowledgebase entries and roughly 180 documents in total. Every one of those knowledgebase files exists because something broke, I figured out why, and I wrote down the answer so it would not cost me a second afternoon.

Then I broke one of them again anyway. A fix from earlier in the year, written up properly at the time, came back months later in a different file where the same mistake was easy to make. The knowledge was not missing. Nothing pointed at it. I had turned my documentation into a library with no catalog, which is a pile.

That is the part people skip when they talk about giving an AI project memory. Writing the lesson down is the cheap half. The expensive half is making sure the lesson shows up at the exact moment somebody is about to need it, and neither I nor any assistant is going to read 54 files before starting a task.

Index by trigger, not by topic

The fix was one more file whose only job is routing. It does not contain any lessons. It says which lessons are mandatory reading for which kind of work.

The thing that makes it work is that the entries are not organized by subject. They are organized by the moment. Not “here is the document about sprite rendering,” but “read this before you darken a sprite that has child sprites,” and “read this when the art shows up in the editor but not in the game.”

That second phrasing is deliberately symptom-shaped. It is written the way I would say the problem out loud right before I go looking for help, because that is the only form I will actually recognize in the ten seconds when recognizing it is worth anything. A topic name only finds you if you already know which topic you are in. When you are about to repeat a mistake, you do not know that.

How it is built today

One file, around 560 lines. It opens with the short list of documents that get read at the start of every session no matter what the task is, so the identity rules and the current state are never optional.

After that it is sections, and each section has the same four parts:

Read the specific files, with the trigger attached to each one. Use when, a few lines describing the situations that should send you here. Avoid repeating, the actual failures that produced these entries, stated as failures. Minimum verification, what has to be checked before the work counts as done.

The “avoid repeating” block does more work than I expected. Reading the file names tells you a system exists. Reading the list of ways that system has already burned somebody tells you to slow down.

The project’s instruction file points at this index at session start, so it is the second thing loaded rather than something anyone has to remember to go find.

The other half: marking what is dead

A routing layer only helps if the things it routes to are true. An old document that still reads like current guidance is worse than no document, because an assistant searching by keyword will find it, and it has no way to know the decision was reversed four months ago.

So superseded docs get marked in place, at the top, saying what replaced them. Not moved quietly, not left to be inferred from a stale date. The rule I wrote for myself is that agents search by words, not by intent, and an old date is not a word.

The honest limit

The index is a file, so it rots like every other file. When it goes stale it does not fail loudly. It confidently routes you to the wrong place, which is worse than having nothing, because now you have read something and feel covered.

The only thing holding it together is a rule that the index gets updated in the same commit as the lesson it points to. Not the next session, not a cleanup pass. Same commit, or it did not happen.

The deeper limit is that routing depends on my guessing the trigger correctly in advance. If I file a lesson under a symptom I never end up experiencing, it sits there being technically documented and practically invisible. Claude pointed out while we were writing this that librarians and site designers have a name for the general problem, information scent, the question of whether a person hunting for something can tell from where they are standing that they are getting warmer. I had not thought about it in those terms. I had just noticed that the entries phrased as “read this before you do X” were the ones getting used, and the ones named after systems were not.