09. Onboarding and mental models¶

Correction repairs wrong answers. Onboarding prevents wrong expectations. The discipline is to teach users what the AI can do, what it cannot do, and how to use it well — before they form a wrong mental model that no amount of correction will undo.

A platform engineer at a Bengaluru legal-tech company launches an AI contract-review assistant. The feature is technically sound; first-week usage is strong; second-month usage cratered. The user research is sharp: users formed their first mental model from a one-line tooltip ("Ask anything about your contract") and a hero example showing the AI summarising a 40-page document in seconds. Users then asked the AI things it was never built for — "Will this hold up in Bombay High Court?" — got vague answers, and concluded the AI was useless. The team rebuilds onboarding: a 90-second walkthrough showing three things the AI does well (clause extraction, risk flagging, redline suggestions) and one thing it does not (legal advice). Adoption recovers because the second-month users now form an accurate model up front.

This chapter is the onboarding discipline.

What onboarding and mental models is¶

Onboarding and mental models is the discipline of shaping the user's understanding of what the AI is, what it does, what it does not, and how to interact with it — early enough that wrong assumptions do not form.

The mental model is the user's internal theory of the AI. It is built whether you design for it or not. The choice is whether the model the user forms is accurate or not.

Three failure shapes:

Failure	Cause	Consequence
Over-trust	Hero examples imply omniscience	Users defer to wrong answers
Under-trust	Hedging language implies the AI is timid	Users abandon
Wrong shape	Onboarding shows breadth, AI is narrow	Users try unsupported use cases and conclude failure

Onboarding's job is to land the right model on the first session.

What a good mental model contains¶

A user with an accurate model can answer four questions without thinking:

What is this AI for? (the intent)
What kinds of questions does it answer well? (the shape)
When should I not use it? (the boundary)
What do I do when it is wrong? (the recovery)

Onboarding teaches all four. A tutorial that teaches only the first leaves the user to discover the rest by failure — which is expensive trust to spend.

The first-five-minutes principle¶

The mental model the user forms in the first five minutes is hard to overwrite. Onboarding owns those five minutes.

What should be in the first five minutes:

One concrete example of what the AI does well, with a clear input and output.
One concrete example of what the AI does not do, framed honestly ("for legal advice, talk to your counsel").
One example of correction — the AI was wrong, the user pushed back, the AI adjusted.
The path to a human, made visible from the start.

What should not be in the first five minutes:

A list of features.
Hyperbolic claims ("intelligent," "thinks like you," "knows everything").
A blank "ask anything" box with no scaffolding.

The blank box is the most common onboarding failure. It maximises perceived freedom and minimises mental-model formation.

Onboarding shapes¶

Inline tooltips. Brief, context-specific. Useful for surfacing affordances ("Click this to see reasoning"). Insufficient for shaping the model.

Guided tour. A scripted walkthrough of two or three core flows. Higher mental-model fidelity. Risk: tedious if too long; skippable if too short.

Worked example. The AI demonstrates itself on a real example with annotations. The most informative onboarding for AI products because it shows the AI in action, including its uncertainty and recovery.

Persona-tailored. Different onboarding paths for different user roles (analyst vs. executive, novice vs. expert). High cost; high payoff if the audience is mixed.

Just-in-time. No upfront tutorial; the AI surfaces capability hints contextually as the user navigates. Lower friction; slower model formation.

Most products end up with a mix — a short guided tour plus just-in-time hints. The choice depends on the product's complexity and the user's prior exposure to similar AI.

The capability map¶

Users need an internal map of what the AI does. Onboarding can supply one explicitly:

"Things this AI does well" — three to five concrete examples.
"Things this AI cannot do" — two or three honest exclusions.
"Things this AI does, but you should verify" — the qualified-confidence zone.

The discipline is honesty about exclusions. A product that hides exclusions hopes users will not test them; they will. The first time the AI fails on a hidden exclusion, the user concludes the entire system is unreliable.

A common pattern that works: a small "What can I ask?" panel that lives in the surface throughout the session, not just during onboarding. Returning users glance at it; new users read it. It costs little and pays repeatedly.

The first-failure handling¶

A user's first encounter with AI failure is a load-bearing moment. If onboarding has prepared them — "the AI gets things wrong sometimes; here is how to correct it" — the failure is annoying but not trust-destroying. If onboarding has not prepared them, the failure is the moment they form the "this AI is broken" mental model.

Practical move: include a deliberately edge-case example in onboarding where the AI either refuses or gets it partly wrong, and show the correction flow. This is uncomfortable to ship — teams want the demo to look perfect — but it pays back fast. The user has seen failure handled gracefully; the real failure later does not surprise them.

Re-onboarding¶

Users forget. Models drift. Features change. A one-time onboarding is insufficient for a product that evolves.

Re-onboarding shapes:

Changelog inline. When a capability changes, the AI mentions it the next time the user uses the affected flow.
Quarterly walkthroughs for high-touch products. Optional, dismissible.
Capability discovery in context. The AI offers a new capability when a relevant user query is detected.

The principle: the mental model needs maintenance, not just installation.

Onboarding metrics¶

What to measure:

Completion rate of the onboarding flow.
Time-to-first-successful-interaction (first query that the user does not abandon or correct).
Frequency of "support" or "help" queries in the first session — a proxy for an inadequate model.
Long-term retention by onboarding cohort — did changes to onboarding shift the retention curve?

What not to measure as primary:

Onboarding screen views. A user can scroll past every screen and learn nothing.
Self-reported confidence. People over-report confidence after a tutorial regardless of actual model accuracy.

The ground truth is whether the user makes effective use of the AI in the following week.

Common mistakes¶

Hero examples that imply omniscience. The summary of a 40-page document in seconds reads as "the AI knows everything"; the user then asks the AI for legal advice.

Hiding exclusions. Users discover exclusions by failing on them and lose trust.

Blank "ask anything" box. Maximum freedom, minimum model formation. Users do not know where to start.

Feature lists. "The AI can do X, Y, Z, and more." Lists do not shape models; concrete examples do.

No first-failure rehearsal. The user's first encounter with AI failure is unmediated.

One-time onboarding. No re-onboarding when capabilities change.

Interview Q&A¶

Q1. The team launched an AI feature with a tooltip and a hero example. Second-month usage collapsed. What is the diagnosis? The mental model formed in the first session was wrong. The hero example implied breadth the AI does not have; users then asked unsupported questions, got vague answers, and concluded the AI was useless. The fix is explicit onboarding: three things the AI does well, one thing it does not, the correction flow demonstrated, the human path visible. Re-launch with onboarding plus inline "what can I ask?" panel; measure second-month retention as the metric, not first-day clicks. Wrong-answer note: "tooltips are sufficient" mistakes affordance hints for model formation.

Q2. Walk through a good onboarding flow for an AI assistant. Three things, in order. First, a worked example: the AI does a real task end-to-end on a representative input, with annotations explaining each step. Second, a capability map: "Things this AI does well," "Things you should verify," "Things this AI does not do." Third, a failure-handling rehearsal: show the AI getting something wrong and the user correcting it, plus the escalation path. Skippable but not hidden. Under five minutes total. The aim is mental-model formation, not feature enumeration. Wrong-answer note: "list all features" produces inventory, not understanding.

Q3. The team is debating whether to show the AI making a mistake during onboarding. What is your view? Show it. The first encounter with AI failure is a load-bearing moment; if it happens in onboarding with the correction flow demonstrated, the user has a frame for handling failure later. If the first failure happens unprepared, the user forms a "this AI is broken" mental model that is hard to undo. The discomfort of showing imperfection in the demo is outweighed by the durability of an accurate mental model. Wrong-answer note: "the demo should look perfect" optimises for the first impression and damages every later impression.

Q4. How do you handle re-onboarding when a capability changes? Inline changelog in the affected flow — the AI mentions the change the next time the user encounters it. Optional walkthrough for major changes, dismissible. Capability discovery in context — when a user query is relevant to a new capability, the AI surfaces it. Avoid global "what's new" modals that interrupt the user before they have asked. The principle is to update the model in context, not in a separate ceremony. Wrong-answer note: "send an email" tries to update a mental model through a channel the user has no need to read.

Q5. The team measures onboarding screen views as the success metric. What is the gap? Screen views measure scroll, not learning. A user can scroll past every screen and learn nothing. The right metric is mental-model accuracy — measured indirectly through time-to-first-successful-interaction, frequency of "help" queries in the first session, and long-term retention by onboarding cohort. The aim is whether the user makes effective use of the AI in the following week. Wrong-answer note: "completion rate is enough" treats the funnel as the goal instead of the outcome.

What to do differently after reading this¶

Own the first five minutes; do not leave the mental model to chance.
Teach four things: what the AI is for, the shape of good questions, the boundary, the recovery.
Demonstrate at least one failure and one correction in onboarding.
Make exclusions honest and visible, not hidden.
Maintain the mental model with inline re-onboarding when capabilities change.
Measure onboarding by time-to-first-successful-interaction and second-week retention, not by screen views.

Bridge. Onboarding shapes the model in the user's head. Accessibility shapes the experience for users whose access to the AI is shaped by sensory, motor, cognitive, or environmental constraints. The next chapter is the discipline of designing AI UX that serves users beyond the default profile. → 10-accessibility-and-inclusivity.md