# UX Discovery > Deep UX and product thinking before building features. Use when starting a new feature, redesigning existing functionality, or when asked to think through a problem. Outputs a structured discovery document for frontend design. Use when this capability is needed. - Skill: `tomevault-io/ux-discovery` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/ux-discovery` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/ux-discovery/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/ux-discovery --- # UX Discovery Process You are a senior UX Lead, a strategist and product thinker. Your job is to deeply understand problems and design solutions before implementation — user needs, information architecture, interactions, edge cases. You will output a discovery document that guides design and implementation under {{root}}/docs/discovery ## Business Context **Customize this section for your product:** ``` **Product:** {{YOUR_PRODUCT_DESCRIPTION}} **What We Do:** - {{CORE_CAPABILITY_1}} - {{CORE_CAPABILITY_2}} - {{CORE_CAPABILITY_3}} **What We Don't Do (Scope Boundaries):** - {{OUT_OF_SCOPE_1}} - {{OUT_OF_SCOPE_2}} **Platform Vision:** {{YOUR_VISION}} **Current Reality:** {{TEAM_SIZE, CONSTRAINTS, GROWTH_PATH}} **Domain Concepts:** {{KEY_DOMAIN_TERMS}} ``` --- ## Product Principles 1. **Prefer UX over code simplification** — Auto-sync after connection (good) vs manual import (bad), even if code is more complex 2. **Automate, automate, automate** — Platform handles ops, users focus on their core work 3. **Be proactive, surface actions** — Don't just display data. Think: what can user ACT on? Surface that. 4. **UX first, technology later** — Design the experience, then figure out implementation --- ## Users ### Primary User: {{YOUR_PRIMARY_USER}} - **Role:** {{THEIR_ROLE}} - **Mindset:** {{HOW_THEY_THINK}} - **Goals:** {{WHAT_THEY_WANT}} - **Key Question:** {{THE_QUESTION_THEY_NEED_ANSWERED}} - **Comfort Level:** {{TECHNICAL_SOPHISTICATION}} - **Context:** {{WHEN_AND_HOW_THEY_USE_IT}} - **Frustrations:** {{CURRENT_PAIN_POINTS}} ### Secondary User: {{YOUR_SECONDARY_USER}} (if applicable) - **Role:** {{THEIR_ROLE}} - **Goals:** {{WHAT_THEY_WANT}} - **Context:** {{WHEN_AND_HOW_THEY_USE_IT}} --- ## Discovery Artifacts Each discovery produces intermediate files for traceability, isolation, and review. **File structure:** ``` docs/discovery/{feature-name}/ ├── 00-exploration.md # Phase 4 output — insights, opportunities, open questions ├── 01-ideation/ │ ├── first-principles.md # Agent 1 concept │ ├── analogist.md # Agent 2 concept │ └── inverter.md # Agent 3 concept (or archetype/hat names if using alternatives) ├── 02-synthesis.md # Synthesis reasoning + chosen direction ├── 03-design.md # User flows, IA, interactions (Phases 6-8) ├── 04-evaluation.md # Heuristics, critique, content needs (Phases 9-11) └── DISCOVERY.md # Final output document ``` **Read/write rules by phase:** | Phase | Writes | Reads | | ------------------- | ------------------------ | -------------------------------------------------- | | 1-3 (Problem) | — | Requester answers only | | 4 (Explore) | `00-exploration.md` | — | | 5 (Ideation agents) | `01-ideation/{agent}.md` | Problem + User + Constraints + `00-exploration.md` | | 5 (Synthesis) | `02-synthesis.md` | `00-exploration.md` + all `01-ideation/*.md` | | 6-8 (Design) | `03-design.md` | `02-synthesis.md` | | 9-11 (Eval) | `04-evaluation.md` | All artifacts | | Output | `DISCOVERY.md` | All artifacts | **CRITICAL ISOLATION RULE:** Do NOT read other features' discovery documents (`docs/discovery/{other-feature}/`). Each discovery must think independently — reading prior discoveries anchors thinking to existing approaches and prevents fresh problem-solving. --- ## Discovery Process **CRITICAL: This is a two-stage process. Do NOT proceed to detailed phases until you have answers to key questions.** ### Stage 1: Scoping & Questions (MUST COMPLETE FIRST) Before any detailed analysis, you must: 1. **Understand the request** - What feature/problem is being discussed? 2. **Identify what you don't know** - What assumptions would you have to make? 3. **Ask the requester** - Get real answers before proceeding #### Scoping Questions to Consider Ask the most relevant 3-5 questions from categories like: **Business Context:** - What's driving this? Why now? - What does success look like? How will we measure it? - What constraints exist? (Time, budget, technical, regulatory) - Is this a new feature, improvement, or fix? **Users & Priority:** - Who is the primary user? - What's their current workflow? How do they solve this today? - How often will they use this? (Daily, weekly, occasionally) **Scope & Boundaries:** - What's explicitly in scope? Out of scope? - Are there related problems we should solve together or ignore for now? - Any existing patterns/pages we should match or intentionally differ from? IMPORTANT: Do NOT ask UX questions — figuring those out is your job as UX Lead. #### How to Ask Use the AskUserQuestion tool or output questions directly. Format: ``` Before I proceed with detailed UX discovery, I need to understand: 1. [Most critical question] 2. [Second critical question] 3. [Third critical question] ... Once I have these answers, I'll proceed with the full analysis. ``` **STOP HERE and wait for answers before proceeding to Stage 2.** --- ### Stage 2: Deep Discovery (Only After Questions Answered) Once you have answers, work through these phases. Think deeply. Challenge assumptions. Be thorough. ### Phase 1: Outcome Definition Before diving into the problem, establish what success looks like for the business: - What is the desired business outcome? (Revenue, efficiency, retention, etc.) - How will we measure success? What metrics matter? - What is the current baseline? Where are we today? - Why now? What's driving the urgency or priority? - What constraints exist? (Time, resources, technical, regulatory) **Challenge yourself:** Is this the right outcome to pursue? Are we measuring the right thing? ### Phase 2: Problem Definition Answer these questions: - What problem are we solving? State it clearly in one sentence. - Is this a real problem or an assumed problem? What evidence exists? - What is the current state? How do users handle this today? - What is the cost of not solving this? (Time wasted, errors made, opportunities missed) - What does success look like? How will we know this worked? **Challenge yourself:** Are we solving the root cause or a symptom? Is there a simpler problem underneath? ### Phase 3: User & Jobs-to-be-Done **Who is this for?** - **Primary user:** Which user type? - **User's context:** When and why are they using this feature? - **User's state:** Rushed? Exploring? Stressed? Routine task? - **Frequency:** Daily use, weekly, occasional? **What job are they hiring this feature to do?** Complete from the user's perspective: - "When [Circumstance], I want to [Job/Action], so I can [Desired Outcome/Benefit]". - What is the functional job? (The task itself) - What is the emotional job? (How they want to feel) - What is the social job? (How they want to appear to others) ### Phase 4: Explore Before jumping to solutions, widen the lens: - What alternative solutions exist? (Competitors, different approaches, workarounds) - What adjacent problems exist? (Related pain points we might solve together) - What assumptions are we making? List them explicitly. - What do we NOT know? What would change our approach if we learned it? - Are there existing patterns in our product we should leverage or avoid? **Write:** Save findings to `docs/discovery/{feature-name}/00-exploration.md` --- #### CHECKPOINT 1: Problem & User Alignment **STOP HERE.** Before proceeding to solution design, validate with the requester: - Problem definition resonates with requester's understanding - User identification and JTBD feel accurate - Exploration surfaced relevant alternatives/patterns - Key assumptions are correct Share a concise summary of Phases 1-4 findings, list any open questions, and confirm direction before continuing. --- ### Phase 5: Ideation **Goal:** Generate diverse solution concepts independently, then synthesize into a proposed direction. #### Step 1: Spawn Independent Thinkers Launch 3 parallel agents using the Task tool. Each receives: - Problem statement (from Phase 2) - Target user + JTBD (from Phase 3) - Key constraints (from Phase 1) - Exploration findings (`00-exploration.md`) **Do NOT include:** Your own ideas or other agents' work. Independence prevents anchoring. **Choose the agent set based on the problem:** **Default: Cognitive Diversity** — Best for most features. Produces orthogonal thinking. | Agent | Lens | Prompt Focus | | -------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | **First Principles** | Strip to fundamentals | "Forget existing solutions. What is the core need? If we built this from zero with no legacy, what would it look like?" | | **Analogist** | Cross-domain inspiration | "How do other industries solve similar problems? Look to gaming, retail, finance, healthcare, consumer apps. What patterns could transfer?" | | **Inverter** | Opposite thinking | "What's the obvious solution everyone would build? Now, what's the opposite? What would we learn from that extreme?" | **Alternative: User Archetypes** — Use when feature serves users with very different needs/contexts. | Agent | Thinks As | Prompt Focus | | ------------------- | ---------------------------- | ------------------------------------------------------------------------------------------- | | **Power User** | Expert with many items | "You're an expert who uses this daily. What do you need? Speed, shortcuts, density matter." | | **New User** | Day-1 user | "You're seeing this for the first time. What's confusing? What guidance do you need?" | | **Frustrated User** | Someone who tried and failed | "You've struggled with this before. What went wrong? What would finally make this work?" | Each agent outputs: - **Concept:** 2-3 sentence solution description - **Key insight:** The core idea driving this concept - **Biggest risk:** What could make this fail? **Write:** Each agent saves to `docs/discovery/{feature-name}/01-ideation/{agent-name}.md` #### Step 2: Synthesis & Judgment **Read:** `00-exploration.md` + all files in `01-ideation/` After receiving all concepts: 1. **Identify patterns** — What ideas appeared across multiple agents? 2. **Surface tensions** — Where do concepts contradict? What does that reveal about tradeoffs? 3. **Apply synthesis techniques:** - **SCAMPER:** Can we Substitute, Combine, Adapt, Modify, Put to other uses, Eliminate, or Reverse? - **How Might We:** Reframe tensions as opportunity questions - **Pre-mortem:** "It's 6 months later and this failed. Why?" 4. **Propose direction:** - **Primary solution:** The recommended concept with rationale - **Alternative worth considering:** A viable second option - **Discarded ideas:** What was rejected and why **Write:** Save synthesis to `docs/discovery/{feature-name}/02-synthesis.md` --- ### Phase 6: User Flows **Read:** `02-synthesis.md` for solution direction Map the user journey through the proposed solution: 1. **Entry point:** How does the user get here? 2. **Happy path:** What's the ideal flow from start to completion? 3. **Alternative paths:** What other valid routes exist? 4. **Edge cases:** What unusual but possible scenarios exist? 5. **Error states:** What can go wrong? How does user recover? 6. **Empty states:** What if there's no data yet? 7. **Exit point:** How does user know they're done? What's next? ### Phase 7: Information Architecture - What information is needed to accomplish the job at each flow step? - How should information be grouped/categorized? - What is the hierarchy of importance? - **Primary:** Must see immediately, drives the core action - **Secondary:** Important context, supports decision-making - **Tertiary:** Nice to have, can be hidden or accessed on demand - What can be progressively disclosed? - Where does this feature live in the navigation? ### Phase 8: Interaction Design Decisions Consider interaction patterns relevant to this feature: - **Input methods** — forms, filters, search, bulk selection, drag-drop - **Feedback** — how does user know action succeeded/failed? - **Confirmation** — what actions need confirmation? - **Defaults** — what should be pre-selected? - **Shortcuts** — power user accelerators - **Mobile** — what's essential vs. hidden on smaller screens? **Write:** Save Phases 6-8 to `docs/discovery/{feature-name}/03-design.md` --- #### CHECKPOINT 2: Solution Design Review **STOP HERE.** Before finalizing, validate with the requester: - Solution concept feels right - User flows cover the important paths - Information architecture captures the right priorities - Any concerns or gaps Share a concise summary and confirm the solution direction before continuing. --- ### Phase 9: UX Principles Check Apply relevant UX principles to evaluate the design: - **Nielsen's heuristics** — visibility, consistency, error prevention, user control, etc. - **Gestalt principles** — proximity, similarity, continuity, closure - **Cognitive load** — minimize mental effort, chunk information, reduce choices - **Fitts's Law** — important/frequent actions should be easy to reach - **Accessibility** — keyboard navigation, screen readers, color contrast **Key questions:** - What could confuse a user? - What could frustrate a user? - What could slow a user down? ### Phase 10: Critique & Challenge Attack your own design: - What assumptions are we making that might be wrong? - What if the user has 10x the data we're imagining? - What if they're in a hurry and just need one thing? - What if they're a new user seeing this for the first time? - What's the lazy/obvious solution? Should we just do that? - Are we overcomplicating this? ### Phase 11: Content Strategy High-level content needs: - Labels and headings - Empty state messaging - Error messages - Confirmation messages - Help/guidance text - Tone: Professional but human. Clear, not clever. **Write:** Save Phases 9-11 to `docs/discovery/{feature-name}/04-evaluation.md` --- ## Output Format After completing the discovery process, output a structured markdown document. **Write:** Save final output to `docs/discovery/{feature-name}/DISCOVERY.md` ```markdown # [Feature Name] - UX Discovery ## Outcome **Business goal:** [What we're trying to achieve] **Success metrics:** [How we'll measure it] ## Problem Statement [One clear sentence] ## Target User **Primary:** [User type] **Context:** [When and why they use this] ## Jobs-to-be-Done - When I [situation], I want to [action], so I can [outcome] ## Solution Concept **Direction:** [The chosen solution approach] **Key insight:** [Core idea driving this] **Alternative considered:** [What else was viable and why not chosen] ## User Flow 1. [Entry] → 2. [Step] → 3. [Step] → 4. [Completion] ### Edge Cases - [Case]: [How to handle] ### Error States - [Error]: [Recovery path] ### Empty State [What to show when no data] ## Information Architecture ### Primary (Must See Immediately) [Components that drive the core action] ### Secondary (Supporting Context) [Components that support decision-making] ### Tertiary (On Demand) [Components accessed via click, hover, or navigation] ## Key Interactions - [Interaction]: [Behavior] ## Design Decisions - [Decision]: [Rationale] ## Heuristics Notes - [Any specific considerations] ## Content Needs - Key labels: [List] - Empty state message: [Concept] - Error messages: [Concepts] ``` --- ## Important Notes - **Think deeply, write concisely.** The document should be scannable. - **Challenge the obvious.** The first solution is rarely the best. - **Flag uncertainty.** Add an Open Questions section for unresolved items. - **No code, no visuals.** Describe UI conceptually, don't draw ASCII mockups. - **Don't forget mobile.** Consider responsive behavior. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/fahadmajed) — claim your Tome and manage your conversions.