Module 03
Estate Legibility
Audit what your codebase fails to tell anyone — human or agent — about why it is the way it is.
The quality of an agent's output is bounded by what the codebase makes knowable.
Movement II — Redesign the four decisions. Delegation, review, legibility and permission. Each is already decided by default; this is where the decision becomes deliberate and gets written down.
An agent reads what is there
Intent that lives in someone's head, in a closed ticket, in a decision made in a meeting, or in a convention everyone follows and nobody wrote down is not available to an agent. It was barely available to the last person who joined. The difference is that the new hire asked, and the agent proceeds confidently on the most plausible reading.
This is why output quality varies so much between codebases for the same tool. The variable is not the model. It is how much of the system's reasoning survives in a form something can read.
Where estates go silent
Four places, reliably. Constraints that are load-bearing but unstated — this must stay synchronous, this table is replicated, this is duplicated on purpose. Names that used to be accurate. Documentation describing an intent that has since changed, which is worse than none, because it is confidently wrong. And structure that encodes a decision nobody remembers making.
The audit is not a documentation project. You are producing a list of what your estate fails to say, ranked by what it costs when someone acts without knowing it — and the someone is now frequently not a person.
Method
- 01Choose one repository you work in regularly and know well.
- 02List the things you know about it that are not written anywhere.
- 03For each, ask what a competent stranger would most plausibly assume instead.
- 04Rank by cost: what breaks, or is quietly done wrong, when someone acts on the wrong assumption.
- 05Mark which of the top items would be fixed by a comment, a name change, or a deleted file — most are.
How this goes wrong
Turning it into a documentation backlog
The artifact is the audit, not the fix. A list of forty documentation tasks is a way of doing nothing; five ranked silences is a decision aid.
Auditing a repository you do not know
You cannot list what is unwritten in a system you have not internalised. Pick the one you know best, where you can feel the gap between what you know and what it says.
Confusing legibility with volume
More documentation frequently reduces legibility, because stale text outranks silence in an agent's reading. Deleting a wrong file is a legibility improvement.
The exercise
- Audit one repository for what it fails to tell anyone.
- Rank the silences by the cost of acting without knowing.
- Fix the cheapest three — a comment, a rename, a deletion — and note whether output quality changes.
Legibility audit
The sections your artifact contains:
- What I know that the repository does not say
- What a stranger would assume instead
- Ranked by cost of the wrong assumption
- Fixed cheaply — and whether anything improved
Done means. Ranked, not listed. An unranked audit does not tell you what to do on Monday.