Legibility

What It Is

A change can be merged without being released. If the product never shows that distinction, a user may assume the change is live and later conclude that the product does not work. The system retained the state, but the person who needed to act on it could not read it.

Legibility means making a system's internal state readable by the agents who need it. Whether the system is working, accumulating value, spending money or failing does not affect those actors unless they can see that state. Agents act on what they can read. The same law applies to a product's users, a startup's team and a person looking at their own life.

"Something has to be legible for me to feel like it's real."

Invisible state produces churn in a functioning product, blame in a sound organization and paralysis in a life that is progressing. Instrumentation makes the state available to judgment. Persuasion cannot substitute for a missing view; once the state is readable, trust follows from what the actor can see.

A display is useful when it reveals a decision-relevant state; merely exposing more information is not the same as making it legible.

Read this diagram

Something changes → The state becomes visible → Someone understands it → They can act.

The Product Case: Three Gaps, One Shape

Agent products hold more consequential internal state than a form or document, making three gaps especially common.

Cost legibility shows what is being spent on the user's behalf. A metered API or an AI assistant can spend ten dollars in a single turn, leaving the balance change as the user's first indication. People routinely accept large known costs. Unknown spending prevents trust because its size is discovered only afterward.

Deploy-state legibility distinguishes building from deploying, saving from publishing and merging from releasing. When those differences are hidden, the user and system maintain incompatible accounts of what is live. The discrepancy appears later as a product failure even when the operation itself worked.

Automation observability shows what background work is doing and where its result is delivered. An automation can run exactly as requested, consuming resources, but supply neither an update nor a delivery channel. To the user it is indistinguishable from waste, producing resentment instead of a reason to keep using it.

A product that fails to earn trust needs an inventory of states its users are asked to take on faith. Legibility sets the ceiling on that trust. “Users don't get it” almost always means the information they would need has not been exposed.

Invisible State Gets Moralized

A startup's state often lives across several people's heads, with the CEO coordinating pieces that no one else can see in full. When the company fails, the CEO is the visible object to blame while the actual mechanism remains unavailable:

"when the startup goes wrong, it gets moralized onto the CEO because the state was invisible. I want to build a startup from the ground up with everything explicit and auditable."

Humans need a causal account. If no mechanism can be read, an invented character trait fills the gap. Moralizing vs Mechanistic replaces that verdict with a mechanism, but the mechanism must first be observable. Legibility is therefore a prerequisite for the explanation.

An auditable startup records its working and failing systems on a timeline, including the founder's judgments. “The CEO lacked focus” can then be examined against the decisions and states that produced the outcome. The record makes diagnosis possible where a visible person had previously been the only available explanation.

Legibility Precedes Motion

An AI agent needs a representation of the environment it can compute over; an unreadable one produces no useful action. Some people need a similarly explicit account before they can participate. Will described that requirement in his own terms:

"I can't just ambiently join a job or group without actually seeing how it serves… I need to make it legible computationally to understand… I'm like an agent. I think I am actually an AI agent."

Most people can act within structures they do not fully understand. For this type of agent, an opportunity becomes joinable only after its role fits into a comprehensible framework. Missing legibility produces stillness rather than rebellion.

Writing the model, exposing the states and naming the interfaces supplies the missing condition. More pressure on motivation does not. The same requirement applies when designing an environment for other agents: readability has to be present before they can act, rather than added as finishing polish.

Shared vocabulary can create the problem across an industry. A term that refers to too many different things leaves participants unable to coordinate around a common state:

"The term agent is holding the industry back… this confusion actually stops a lot — you can't make progress with it… At least for me, I don't know what I'm doing unless it's legible to me."

An imprecise label does not make the underlying situation readable. Coordination can stall on the word “agent” for the same reason a user stalls on a hidden deploy state.

Instrumenting Yourself

Tracking makes personal state observable so that a narrative can be tested against what happened. Legibility adds a consequence for mood: anxiety about the future often comes from an unreadable present.

The fear that nothing is working extrapolates today's apparent state into the next month or year. That extrapolation runs only because progress is not visible; the future looks like repetition. A dashboard, a body of work or photographs across months can show that the retained state has changed, giving a different basis for expecting tomorrow.

The observation interval has to match the change. Someone losing weight may see no difference from one day to the next and conclude the system is failing. Comparing photographs months apart makes the progress visible. The relevant diagnosis may be that the person has not looked at an interval where the effect can be seen.

Macrostate Engineering therefore requires a visible tracker. It exposes the current state, supplies feedback and allows convergence toward the target. A target held only in the head does not converge, and progress held only in memory does not provide reassurance. The record has to become available at the moment of assessment.

Boundaries

Clarity examines undefined variables in a person's own plan: goal, action, transition model and effort bound. Its seven questions apply when the plan itself is unreadable. Legibility is broader: it concerns whether any actor can read the state they must respond to. When the plan is clear but the surrounding world is unreadable—or other people cannot read the state you need them to respond to—the missing work is instrumentation.

Memory Is the Substrate applies this to records across time. Notes flattened for neatness can conceal distinctions and mislead a future interpreter. That future reader is another agent acting on the state being written now.

Related Concepts

• Tracking makes personal state observable before diagnosis.
• Moralizing vs Mechanistic replaces character verdicts once the mechanism is visible.
• Macrostate Engineering uses a visible tracker for feedback and convergence.
• Cybernetics requires sensors that can read the environment.
• Clarity identifies undefined variables in a plan.
• Memory Is the Substrate preserves readable state for later interpretation.
• Invokable Structures supplies the capabilities that make a goal's actions legible.
• Information Architecture gets the relevant state to the person who needs it.
• Error Signal makes a difference between intended and actual state readable enough to act on.