The map

The failure the map exists to prevent

The doors from the last chapter keep the wrong people out. They do nothing about the files themselves drifting apart.

Here is the failure the map exists to prevent. It is a shape, not one dated incident, and it is the shape my brain warned me about in its own words.

A brain made of plain files is easy to hold in your head... for a while. Past a few hundred files, two things can happen that you cannot see from the inside.

The first is quiet. An agent loads a file, trusts it, and acts on it. The file looks fine: well written, dated, sure of itself. But nothing points to it any more. The thing it described has moved on, the newer version lives somewhere else, and this one was left behind. The agent has no way to know it is reading a ghost.

The second is louder, but only later. A rule changes, for a good reason. The other files that lean on that rule keep saying the old thing. No error. No warning. Just a brain that now disagrees with itself, waiting for an agent to pick the wrong side.

My brain wrote the lesson down about itself: "A document describing a control drifts from the control, silently and in both directions."

In a small brain, I am the index. I know what cites what because I wrote it last week. Past a certain size, I am not, and grep only tells me where a word appears. It does not tell me what depends on what.

The hire had a desk, keys and rules. It needed a map of the building.

The idea

The map is a way to navigate, not a source of truth.

Every file in the brain already says what it leans on. It cites other files by name, links to them, quotes their paths. Those references are a network that nobody ever draws. The map draws it.

Then I can ask the one question that matters before an edit: if I change this, what else moves?

How it works

The map reads the brain and collects every reference one file makes to another. It does not guess and it does not ask an AI to infer connections. If a file names another file, that is a line on the map. If it does not, there is no line. Every connection on the map was written down by someone.

That gives three uses, and one protection.

Ripple. Before I change a rule, I ask the map what points to it, and what points to those. One step out shows the files that cite it directly. Two steps out shows the ripple. Then I go and read those files, because the map tells me where to look, not what they say.

Tap to enlarge

Close

Before I change a rule, I read the files that cite it and the files that cite those. Made-up example.

Orphans. Files with nothing pointing to them get listed. An orphan is not automatically junk. It might be a starting point, or something used by habit. But it is a file an agent could trust without anyone checking whether it still holds. So it gets looked at.

Broken paths. A reference to a file that no longer exists shows up as a break. Those are the easiest drift to catch, and the most embarrassing to miss.

The private zones. This is the part I cared about most. Some folders hold client work, raw recordings and drafts. The map never reads inside them. If a file points into one of those folders, the whole folder collapses into a single closed box on the map. So the map can never draw a line between two confidential areas. It cannot join client room A to client room B, because it has never been inside either.

     instructions ──────► rule: "ask before naming"
                               ▲        ▲        ▲
                               │        │        │
                     critic check   draft skill   a learning  
                                        │
                                        ▼
                               ┌──────────────────┐
                               │ [client work]    │  a zone: one closed box,
                               │  never opened    │  never read, never joined
                               └──────────────────┘

     orphan:  old-pricing-note.md   (nothing points here. Look before trusting.)
     broken:  skills/send-recap.md ──► wiki/recap-template.md  (missing)

The map rebuilds itself when the brain has changed since it was last drawn, so it does not go stale the way the files it watches can.

What I learned the hard way

Validate the detector before you act on what it flagged. My brain wrote that lesson about itself. A map that lists a file as an orphan is a detector, and detectors are wrong in specific ways. An orphan only means nothing in the brain links to it. It does not mean nobody uses it. Treating the orphan list as a delete list would be the fastest way to break something.

Tap to enlarge

Close

Three files flagged as orphans, and only one of them should go. Made-up example.

The busiest file lies to you. My main learnings file links to almost everything. Walk two steps out through it and you get half the brain back, which is the same as getting nothing. So I read the neighbours of the busiest files selectively, instead of trusting the full list.