القائمة
Use when identifying where user mental models diverge from system reality, where moments of truth occur, and where information scent misleads — finds the structural causes of confusion
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use when writing Rails controllers or implementing state changes - enforces resource extraction, thin controllers delegating to models, params.expect, and controller concerns for scoping
Use when designing database schema, writing migrations, or making data storage decisions - enforces UUIDs, account_id multi-tenancy, no foreign keys, and proper index patterns
Use when writing Hotwire (Turbo/Stimulus) code in Rails - enforces dom_id helpers, morph updates, focused Stimulus controllers, and JavaScript private methods
Use when writing background jobs or async operations - enforces thin job wrappers (3-5 lines) that delegate to models using _later/_now naming pattern
Use when writing Rails models - enforces state-as-records not booleans, concerns as adjectives namespaced under model, and concern extraction triggers
Use when naming classes, methods, routes in vanilla Rails codebases - enforces concern adjectives (-able/-ible only), no bangs for state, resource naming cascade, and commit message format
| name | gap-analysis |
| description | Use when identifying where user mental models diverge from system reality, where moments of truth occur, and where information scent misleads — finds the structural causes of confusion |
Core principle: Every gap between what users believe is happening and what's actually happening is a design failure waiting to surface. Map the gaps, find the structural causes.
For each touchpoint or step, document:
| Column | What it captures |
|---|---|
| User belief | What users predict will happen, based on cues and prior experience |
| System reality | What actually happens — read routes, controllers, views, mailers |
| Consequence | Confusion, error, churn, support load — the cost of the gap |
| What would close it | The design change that aligns model to reality |
Code analysis reveals system reality directly. User beliefs require inference from labels, copy, affordances, and known interaction patterns. Separate confirmed from inferred.
Every crossing of the line of interaction is a moment of truth — an encounter with outsized power to shape trust. For each crossing, capture: expected mental model, likely emotional state, failure modes, and visible evidence shaping perception. Cross-reference the blueprint's interaction line to find these crossings.
Assess whether labels, cues, and surrounding context help users estimate the value of each path. Weak scent causes confusion and backtracking even when the right answer exists in the system. Misleading scent is worse — it builds false confidence. Rate each location: strong, weak, or misleading.
Evaluate complexity timing across three phases. Early (onboarding, first contact): overwhelmed or appropriate? Mid (core task): sufficient or noisy? Late (completion, edge cases): starved or adequate? Flag phase mismatches — too much too early, too little too late.
This skill is most powerful after service-design:service-blueprint and service-design:empathy-analysis exist for the slice. It cross-references both: the blueprint provides the interaction line and backstage structure, the empathy analysis provides the emotional and informational layer. Can run standalone but yields less precise results.
Tag every claim: [confirmed] (verified in code, docs, or data), [hypothesis] (inferred from patterns or analogous systems), or [gap] (unknown). Mental model gaps derived from code analysis are [confirmed] on the system-reality side; the user-belief side is almost always [hypothesis] without direct research. Note what would confirm each hypothesis.
Write to docs/service-design/<slice>/gap-analysis.md using the template at service-design/templates/gap-analysis.md. Populate Mental Model Gaps, Moments of Truth, Information Scent, Progressive Disclosure Check, and Priority Gaps sections.
