Mental Models

Concept of the skill

Three-model frame (designer's model / system image / user's model) plus the two gulfs (execution: "how do I do what I want to do?" and evaluation: "what did the system actually do?") between them. The interface is the only channel from designer's model to user's model; everything else (intent, internal docs, design rationale) is invisible to the user. Layered on top: five failure modes (transfer, overgeneralization, underspecification, drift, invariant blindness) each with their characteristic intervention; four model layers (surface / operational / architectural / domain) describing different depths of understanding; cross-domain application — UX, distributed systems, type systems, API design, team collaboration all reduce to model-vs-system fit and how to align them.

Replaces "whose fault was that surprise" with "where did the model diverge from the system." Without mental-models discipline, every confusing UX moment, every "user error," every miscommunication, every bug-shaped misunderstanding looks like an isolated incident — and the response is either to train the user or developer harder (rarely works; the model came from somewhere) or to add documentation (rarely read; arrives too late). The discipline replaces blame-finding with diagnosis: which of the three models differs from its referent, where, and which intervention closes the gap. The right model for a role is the smallest model that supports successful action in that role — not the most complete one, not the most accurate one in some absolute sense.

Distinct from conceptual-modeling, which owns the formal representation of a domain (entities, attributes, relationships) for downstream use by schemas and APIs — this skill owns the cognitive construct (how a mind represents the system), upstream of any formalism. Distinct from knowledge-modeling, which owns the choice of representation paradigm (graphs, frames, rules, networks) — this skill owns the discipline of reasoning about model-system fit before any paradigm is chosen. Distinct from user-research, which owns the methods for empirically eliciting and validating mental models (interviews, think-aloud, surveys, contextual inquiry) — this skill owns the framing of what a mental model is and how to reason about its accuracy. Distinct from cognitive-biases work (out of scope) — this skill is about model-system fit, not the systematic decision-making errors a mind exhibits. A mental model is to a system what a map is to a city — the map is not the territory, the map is useful precisely because it is smaller and selective, and a traveler navigating with the wrong map (a city map for a different city, an out-of-date map, a tourist map missing the metro) does not get lost because the map is 'wrong' but because the map's selectiveness does not match the route they need. The wrong mental model is that the user's mental model is the user's fault — that confusion comes from inattention or lack of training, and the response is "train harder" or "add a tooltip." The user's model came from somewhere: usually the interface itself, prior experience with similar systems, the analogy the documentation used. The discipline is to ask which signals seeded the wrong model and how the system image can be made to convey the system's actual model honestly. "The user is holding it wrong" is almost never the right diagnosis; "the interface is teaching the wrong model" almost always is, and the right intervention sits at the interface, not at the user.

Coverage

The cognitive discipline of building, evaluating, and aligning the internal representations that minds carry of systems, domains, and interactions. Covers the three-model frame (designer model / system image / user model), the two gulfs (execution and evaluation), the role of analogy and metaphor in seeding new models, the model failure modes (transfer, overgeneralization, underspecification, drift, invariant blindness), the difference between surface, operational, architectural, and domain models, the methods for surfacing and repairing mental models through interface and documentation, and the cross-domain application of mental-models reasoning to UX, distributed systems, type systems, API design, and team collaboration.

Philosophy of the skill

Mental models are how minds make systems tractable. Every user, every developer, every stakeholder operates from a model — partial, private, learned. Most surprise, most "confusing UX," most "miscommunication," most "user error" is the trace of a model-system gap. The disciplined response is to ask which model differs from which referent, where, and which intervention closes the gap — not to ask whose fault the surprise was.

The discipline holds three commitments. First: that the user, the developer, and the system are three distinct sources of truth, each with their own model, none of which is automatically right. Second: that the interface is the bridge through which the system's actual model can become visible enough to repair user models in flight. Third: that the right model for a role is the smallest model that supports successful action in that role — not the most complete model, not the most accurate model in some absolute sense, but the model that does the work and no more.

For agents working in software systems, mental-models discipline is the layer that decides what model to operate from before deciding what code to write. An agent that imports a wrong metaphor — "git branches are tree branches," "React state is OOP state," "a webhook is a function call" — produces code that compiles but doesn't work. The discipline is to make the operating model explicit, to test its predictions against the system, and to surface the gap before it becomes a bug.