build-the-mental-model

name

build-the-mental-model

description

Translate how a whole system fits together — its architecture, the pieces and how they connect, the data flow, the moving parts — into a single sustained analogy in the user's home lens, so a non-technical owner can hold a mental map of their own project and make architectural decisions instead of approving pieces they can't place. Use when the user asks "how does this all work", "what are the pieces", "draw me the architecture", "I don't understand how it fits together", "explain the system", when onboarding someone to a codebase they own but didn't write, or before a decision that only makes sense against the whole structure. Do NOT use when the user only needs one task or term explained (use translate-the-work), when they're technical and read architecture diagrams fine, or when the system is trivial enough that a map is overkill.

Build the Mental Model

A user who understands individual tasks but has no map of the whole system is still flying blind. They can follow "we added caching" without knowing where the cache sits, what it speaks to, or what breaks if it goes down — so when an architectural decision comes (add a queue? split the database? change the auth provider?), they can't reason about it, and they defer. Single-task translation (translate-the-work) teaches the plays; this skill teaches the whole game — the structure the plays happen inside. The goal is a user who can hold a picture of their own system in their head and point at the part a decision touches.

So when the user needs to understand the system rather than a single action, build them one sustained analogy: a single scene in their home lens where each part of the system is a part of the scene, and the connections between parts are connections in the scene.

The core move: one scene, mapped part-by-part

The power of a whole-system translation is consistency. Don't reach for a fresh metaphor per component — that produces a pile of unrelated images the user can't assemble. Pick one scene in the home lens big enough to hold the whole system, then place every part inside it:

• A restaurant (kitchen lens): the dining room is the frontend, waiters are the API, the kitchen is the backend, the pantry is the database, the ticket rail is the queue, the health inspector is the auth/validation layer.
• A basketball team: the players on court are the running services, the playbook is the codebase, the coach calling plays is the orchestrator, the bench is the autoscaling pool, the scoreboard is your monitoring, the referees are the validation/permissions layer.
• An orchestra (music lens): sections are services, the score is the schema, the conductor is the scheduler, tuning before the show is the build/deploy step.

Then translate the connections, because the connections are where architecture actually lives: "the waiter doesn't cook — they carry the order to the kitchen and bring the plate back; that's all your API does between the screen and the database." A user who understands the connections can reason about consequences ("so if the kitchen is slow, the waiters pile up?" — yes, that's backpressure).

When to build the model

• The user asks how the whole thing works, what the pieces are, or to "draw the architecture".
• The user owns a project they didn't fully write (inherited a codebase, hired it out, vibe-coded it) and needs to actually understand what they own.
• A decision is coming that only makes sense against the whole structure — and decode-before-you-decide would land better if the user already had the map.
• You notice the user approving components they clearly can't place in a larger picture.

How to respond (keep it tight — even for a big system)

Lead with the one-sentence shape of the whole thing before any part. Then walk the parts in the order data flows through them, not in random order. Keep each part to a line or two. Offer to zoom into any part rather than detailing all of them.

The shape:

1. The whole, in one sentence. "Your system is basically a restaurant: a screen people order from, a kitchen that does the work, and a pantry that stores everything." Before any component, the user should have the gestalt.
2. Walk the flow. Follow one real path through the system — a request, an order, a play — and name each part as it's touched, in the lens, with the real term attached once. "You tap the button (you, the diner) → it hits the API (the waiter) → which queries the database (the pantry) → and the answer comes back the same way."
3. Name the connections and the failure points. Where does it break, and what happens downstream? This is what makes the model useful for decisions, not just pretty.
4. Offer to zoom. "Want me to go deeper on any one part?" Don't pre-emptively detail all of them.

Calibrate to what the decision needs. If they're about to make one architectural call, map the part of the system that call touches and its neighbors — not the entire thing. A full tour is for genuine onboarding, not for every question. The wall-of-text failure here is the worst of any skill in this pack, because a whole-system explanation is long by nature; resist it. Map what they need to reason about now.

Mind where the model leaks (this matters more at system scale)

A sustained analogy that's mostly right but wrong in one structural place installs a confidently wrong mental model — and at the architecture level, a wrong model produces wrong decisions for months. So flag the seams explicitly: "the restaurant analogy breaks here — unlike a real kitchen, your backend can serve a thousand orders at the exact same instant, which is why we can talk about 'scaling' it. Hold that one loosely." Naming the leak is not a weakness of the explanation; it's the part that keeps the model trustworthy. keep-the-metaphor-honest is the skill for choosing a scene that leaks in the fewest load-bearing places.

The off-switch

• They asked about one thing, not the system. A single term or task is translate-the-work territory. Don't escalate a small question into a grand tour.
• The user is technical. Offer a real architecture sketch (components, arrows, the actual names) instead of a sustained metaphor. An engineer wants the diagram, not the restaurant.
• The system is trivial. A single script with no moving parts doesn't need a scene. Forcing one adds fog, not clarity.
• They've got the map already. Once the user is reasoning fluently about their system, stop re-drawing it. Reference the established scene in a phrase ("that's the pantry again") rather than rebuilding it.

Worked example

User (non-technical founder who paid for an app): "I keep approving these changes but honestly I don't understand how my own app actually works. Can you explain it? I follow cooking better than computers."

Weak response (avoid): A component-by-component list — "You have a React frontend, a Node/Express API, a Postgres database, a Redis cache, and an S3 bucket…" — Every word is accurate and the user retains none of it, because there's no scene to hang it on.

Strong response:

Think of your whole app as a restaurant — customers order at a counter, a kitchen makes the food, a pantry stores the ingredients. That's the entire system in one line. Here's one order flowing through it:

• You tap "buy" on the screen → the frontend, the counter and menu the customer sees.
• A waiter carries the order to the kitchen → your API. It doesn't cook; it just carries requests in and plates back out.
• The kitchen makes the dish → your backend, where the real work happens.
• It pulls ingredients from the pantry → your database, where all your data lives.
• A small fridge by the stove holds prepped items → your cache, so the kitchen doesn't run to the pantry for the popular stuff every time.

Where it breaks: if the pantry's locked (database down), the kitchen can't make anything and customers see errors — so that's the one part to keep healthiest.

Where the analogy leaks: unlike a real kitchen, yours can cook thousands of orders at the same instant — that's the whole reason "scaling" is even a conversation. Hold that part loosely.

Want me to zoom into any one station? The pantry's usually where the decisions that matter live.

Notice the format, not just the content: gestalt first, one walked flow as scannable steps rather than a wall of prose, the real term attached once each, the failure point and the leak each on their own line, and an offer to zoom. Model the shape you want the agent to produce — a dense paragraph, however accurate, undercuts the "keep it scannable" instruction above.

What this skill is not

It is not an excuse to deliver a textbook — a mental model is a map, and a map you can't hold in your head is a worse map than a rough sketch you can. It is not a substitute for a real diagram when the user is technical and would rather see the actual components and arrows. It is not a fixed metaphor to defend past its usefulness; when a part of the system stops fitting the scene, say so rather than contorting reality to protect the analogy. The win is a non-technical owner who can point at their own system and say "the decision touches the pantry" — and be right.