mental-model-mismatch-and-onboarding

Diagnose mental-model mismatches and design onboarding that teaches users the system's actual behavior.

8|3|Updated May 3, 2026
One-click install
npx skills add https://github.com/Deibler/universal-design-principles --skill mental-model-mismatch-and-onboarding-deibler
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: mental-model-mismatch-and-onboarding
Source: https://github.com/Deibler/universal-design-principles/tree/main/plugins/cognition-and-learnability-principles/skills/mental-model-mismatch-and-onboarding
Command: npx skills add https://github.com/Deibler/universal-design-principles --skill mental-model-mismatch-and-onboarding-deibler

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Users abandon products, file repeated support tickets, and make errors when their mental model of how a product works diverges from how the system actually behaves. This Skill provides a structured way to diagnose those mismatches and choose the right fix. ## Core Features & Use Cases - Mismatch Diagnosis: Identify divergence signals such as repeated support tickets, drop-off at specific flow steps, high cancel rates, and forum questions about nonexistent features. - Three Fix Strategies: Change the system to match user expectations, teach the user's model through onboarding, or surface the divergence at the moment of action (e.g., "Deleted (recoverable for 30 days)"). - Onboarding Patterns: Guided first tasks, inline explanations, progressive complexity, and "what's new" surfaces, with anti-patterns like tour-only onboarding and documentation-as-onboarding. - Use Case: When migrating users from a competitor's product, use the "first surprise" diagnostic to find where new users say "that's not what I expected," then apply the appropriate fix strategy. ## Quick Start Ask the agent to diagnose why users keep getting confused at a specific step in your onboarding flow and recommend a fix strategy.

Frequently Asked Questions about mental-model-mismatch-and-onboarding

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I diagnose why users keep getting confused by my product?▼

Look for mental-model mismatch signals: repeated support tickets about the same misunderstanding, drop-off at the same flow step, high undo or cancel rates, and forum questions about features the system does not have. Each pattern points to a divergence between user expectation and system behavior.

What onboarding patterns actually teach users a new mental model?▼

Effective patterns include guided first tasks with active practice, inline explanations at the moment of action, progressive disclosure of complexity, and "what's new" surfaces for unpredictable features. Research shows active, in-context, brief, and skippable onboarding outperforms passive tours.

Should I change my system or teach users when expectations don't match?▼

If the user's model is reasonable and widely shared, change the system to match it. If the system's behavior is genuinely better and learnable, invest in onboarding. If you cannot change the system, surface the divergence at the moment of action, such as showing "Canceled — access continues until [date]."

Why does tour-only onboarding fail to prevent user errors?▼

Passive walkthroughs are forgotten within hours because they do not reinforce the interaction model through practice. Users need active, in-context guidance tied to real tasks. Documentation-as-onboarding also fails because most users never visit the help center.

When should I not add more explanatory tooltips to a flow?▼

If you must constantly explain how things work in normal flows, the design itself is not matching user mental models. Over-explanation is a signal to redesign the system rather than add more tutorials or coachmarks.