ux

# UX Design Hub Routes to specialist sub-skills or runs the built-in 8-step UX pipeline. ## Product quality route `/ux --craft` or a product-quality/onboarding/activation audit selects `craft` before persona/research keyword inference. Load [references/product-craft.md](references/product-craft.md). Inspect supplied evidence, cover all 12 obligations, report unknowns separately from failures, and prioritize three actions. Return inline unless the user requests a saved artifact. This is skill syntax, not a CLI flag. Research-only and wireframe-only requests retain their existing modes; generic coding work does not select craft. Full design runs load the same reference at Problem Framing for principles/brand, Task Decomposition for onboarding/activation, and Interaction Models/Components for states, performance, feedback and tokens. Reuse current artifacts and components. Completion requires evidence or an explicit gap for each relevant obligation; synthetic agreement is a hypothesis, not observed user proof. ## Agentic user research route For **Agentic user research**, day-in-the-life simulations, or persona journeys that affect shared projects across rounds, select `agentic-research` before generic multi-agent, research, or CLI UX inference. Load [references/agentic-user-research.md](references/agentic-user-research.md) only for this method. Reuse Persona Detection, then follow that reference instead of the one-shot Persona Fanout and static persona-by-model matrix. Each tick collects one next decision per person against the same world version. Wait for all responses, validate them, and apply their effects together under recorded product rules before the next tick. Preserve each person's private knowledge and history. A request to document this method changes instructions only; running an experiment requires an execution request. ## Hub Decision Tree ``` Request arrives | +-- Agentic user research / day-in-the-life / shared-world persona simulation? | -> Load: references/agentic-user-research.md | Persona Detection, then synchronized decision ticks and journey analysis | +-- Product quality / craft audit / onboarding / activation? | -> Load: references/product-craft.md (12-rule scorecard) | +-- Product planning (vision, roadmap, data model, export)? | -> Load: skill://lev-design-os | (~/.agents/skills/lev-design-os/SKILL.md + references/) | +-- Visual design / .pen file / design sweep? | -> Use Pencil MCP tools (batch_design, get_screenshot, style guides) | Ref: skillsdb://creative/pencil for character/illustration work | +-- CLI / agentic UX patterns? | -> Load Phase 0.5 lev-ref patterns (below) | +-- User research / personas / study design? | -> Run UX research mode: | Step 1 persona detection + Step 2 persona fanout + domain exploration + problem framing + synthetic user research | Optional: use CDO persona agents if CDO artifacts or "$cdo insights" are present | +-- UX pipeline (wireframes, flows, IA, JTBD)? | -> Run 7-step pipeline (this skill body) | +-- CDO insights / persona base / deliberation synthesis? | -> Run persona detection, compose one CDO agent per situation-specific persona, | then use those findings as persona seed material | Continue into research mode or full pipeline depending on context | +-- "What design skills exist?" / browse? | -> Load `skill://skill-discovery` for this design request. | For corpus-only results use `--namespace skills-db`; filter the physical | UX collection with `--category design-ux`. Use returned subject node IDs | for semantic navigation, never as physical category names. | +-- Ambiguous? -> Infer from local/contextual signals first. If confidence < 0.75, ask one clarifying question with these options: 1. Full UX run 2. User research/personas only 3. Persona base from CDO insights 4. Spike/wireframes only ``` ## Skills-DB Design Catalog (skillsdb://design-ux/*) | Skill | Load when | |-------|-----------| | design-os | Product vision, roadmap, data model, design tokens, export | | superdesign-prompt-library | AI image prompts, style/layout/component prompts | | swiftui-* (6 skills) | SwiftUI/iOS/macOS UI work | | metal-shaders, vfx-spell-effects | GPU graphics, visual effects | ## UX Thinking Patterns (scored, from skills-db) Load from ~/.agents/skills-db/thinking/patterns/{name}/SKILL.md when reasoning depth needed: | Pattern | Score | Use when | |---------|-------|----------| | nielsen-heuristics | 50 | Usability evaluation | | design-of-everyday-things | 48 | Affordance/signifier analysis | | dont-make-me-think | 48 | Simplicity audit | | laws-of-ux | 45 | Psychology-based design | | wcag | 45 | Accessibility compliance | | design-systems | 45 | Component architecture | | refactoring-ui | 44 | Developer-facing design tactics | ## Hub Shortcuts | Key | Action | Route | |-----|--------|-------| | (p) | Product design wizard | skill://lev-design-os | | (w) | Run UX pipeline | Persona-first steps + downstream UX phases below | | (f) | Full UX run | Step 1 persona detection + Step 2 persona fanout + full downstream pipeline | | (i) | Interactive run (interview me) | Same as full, but asks one question at a time with options and a recommendation, and pauses after each step for review | | (r) | User research/personas | Step 1 persona detection + Step 2 persona fanout + research synthesis | | (d) | CDO-backed persona base | Step 1 persona detection + Step 2 CDO persona fanout + research synthesis | | (v) | Visual design / .pen | Pencil MCP tools | | (c) | CLI/agentic UX patterns | Phase 0.5 lev-ref | | (b) | Browse design skills | `skill://skill-discovery` with the design-UX corpus scope | | (k) | Product craft audit | `/ux --craft`: 12-rule scorecard, X/12, top 3 fixes (references/product-craft.md) | --- # UX Pipeline ## Mode Parsing Treat the user's message (including any `/ux ...` text) as the input. - First run the **Intent Resolver** below. Do not default to AUTO until context has been inspected. - If the request selects Agentic user research or describes day-in-the-life persona simulations with shared world state across rounds, set mode to `agentic-research` and follow its route. Generic parsing below must not overwrite this selection, including when the request also says `multi-agent`, `persona`, `full`, or `continue`. Resume its recorded checkpoint when asked. - If the input or nearby context contains `cdo`, `$cdo`, `CDO insights`, `persona base`, `deliberation`, `synthesis`, `multi-agent`, or paths under `tmp/cdo-*`, set mode to `cdo-research` unless the user explicitly asks for only wireframes or only full pipeline. - If the input or nearby context contains `user research`, `synthetic research`, `persona`, `study`, `interview`, `JTBD research`, or `research matrix`, set mode to `research` unless the user explicitly requests full pipeline. - If it contains `full` or `interactive`: ask a small set of clarifying questions first, then run step-by-step. - If it contains `interactive`, `interview`, `interview me` or `ask me`: run interactive mode. Ask ONE question at a time (AskUserQuestion when available: 2-4 options, the recommended one first and labelled, an ASCII preview when the choice is visual), look up anything the repo or prior runs can answer instead of asking, record each answer verbatim in the run folder before the next question, and stop after each pipeline step for review. - When the request is a design for a real product surface and no mode is named, offer interactive mode as the first option of the clarifying question. - If it contains `step N`: in persona-first modes, `step 1` means Persona Detection and `step 2` means Persona Fanout. Otherwise, match the named downstream phase if provided. - If it contains `continue`: resume the most recent run folder under `.lev/ux/`. - If it contains `spike`: skip directly to the Wireframes phase. Sketch the interface based on the request alone — no analysis, no artifacts, just wireframes. After wireframes, optionally back-fill analysis from what was drawn. This is prototype-first design. - If no mode is explicit: - Infer `continue` if the user is referring to an existing `.lev/ux/` run. - Infer `cdo-research` if CDO artifacts are attached, cited, or present as the declared source of persona insight. - Infer `research` if the request asks who the users are, what personas need, what interviews/research should happen, or how to validate a UX/product premise. - Infer `full` if the request asks for an end-to-end product/UX package, flows, IA, research, and wireframes together. - Infer `spike` if the request asks to sketch, mock, wireframe, or make screens quickly with little analysis. - If inference confidence is below `0.75`, ask exactly one clarifying question: `Should I run the full UX pipeline, an interactive run that interviews you step by step, user research/personas only, persona base from CDO insights, or spike/wireframes only?` - In any non-auto mode except `agentic-research`, `spike`, `continue`, or explicit `step N`, use the persona-first sequence: - Step 1: Persona Detection. - Step 2: Persona Fanout. - Step 3: Synthesis into problem framing, research, JTBD, or full UX pipeline. Do not skip straight to problem framing unless the user explicitly says to. - Otherwise: AUTO mode. Run the downstream UX pipeline end-to-end and produce wireframes. ## Intent Resolver Before Phase -1, compile a small routing record: ```yaml ux_intent: inferred_mode: full | auto | interactive | research | cdo-research | agentic-research | spike | continue | step confidence: 0.0 evidence: - "explicit token, nearby context, artifact path, user correction, or prior run" ask_if_below_confidence: 0.75 clarification_question: "Should I run the full UX pipeline, user research/personas only, persona base from CDO insights, or spike/wireframes only?" ``` Context signals to inspect: - Current user message and the last few user corrections. - Files or attachments named by the user. - Existing `.lev/ux/` runs. - CDO outputs under `tmp/cdo-*`, `.lev/pm/`, or paths named by the user. - Product/domain artifacts already on disk. - Whether the user is asking to design the product, validate the users, create personas, or draw screens. Routing rules: - `agentic-research`: run Persona Detection, then load the Agentic user research reference for study setup, synchronized ticks, breadth/depth, and findings. Its own artifact list replaces the generic full-pipeline output list. Existing persona-count and matrix-size advice applies to static studies, not this mode. - `research`: run Step 1 Persona Detection, Step 2 Persona Fanout, Problem Framing, Synthetic User Research, then write `summary.md` and `constraint_bundle.yaml` if the signal is strong enough. Do not continue into wireframes unless the user asked for full pipeline or the gate decision is `proceed` and AUTO mode is active. - `cdo-research`: run Step 1 Persona Detection, Step 2 CDO Persona Fanout, then Synthetic User Research using CDO findings as persona seed material. Continue into full UX only if requested or inferred with high confidence. - `full`: run Step 1 Persona Detection, Step 2 Persona Fanout, Step 0b, then continue through the full downstream UX pipeline. - `auto`: run Step 0b through the full downstream UX pipeline unless self-invalidation aborts. - `spike`: run Wireframes only. - `continue`: resume latest or explicitly named run. Do not ask the clarifying question if the user already selected a mode in plain English. "Let's do research first" means `research`; "base personas on CDO" means `cdo-research`; "full run" means `full`. ## Persona Detection Gate In `full`, `interactive`, `research`, `cdo-research`, and `agentic-research` modes, persona detection is the first step unless the user explicitly bypasses it. Naming rule: in non-auto mode this is Step 1. Step 2 is Persona Fanout. Problem framing happens after fanout synthesis. In AUTO mode, keep the existing pipeline numbering but still run this gate when research/persona context is relevant. Write `persona_detection.yaml`: ```yaml persona_detection: source_context: - "user request, attachments, prior artifacts, CDO outputs, repo/product docs" situation: "{what situation these personas are reacting to}" domain: "{domain or market}" likely_persona_axes: - axis: "{role, authority, risk tolerance, domain expertise, buyer/user, technical literacy, urgency, trust posture}" why_it_matters: "{why this axis changes UX/research response}" candidate_personas: - id: "{persona-id}" role: "{domain-specific role}" personality_type: "{behavioral archetype specific to the situation, not MBTI by default}" context: "{what they know, need, fear, control, and misunderstand}" primary_question: "{what this persona needs answered}" likely_objection: "{what would make them reject the product/design}" source: named_person | role | investor | consumer | buyer | operator | gatekeeper | synthetic named_person: "{name if persona is based on a specific stakeholder, else null}" confidence: 0.0 ask_user_if_below: 0.75 ``` Persona source rule: - If local context names people, each named person plus their role becomes a candidate persona unless the user excludes them. Example: founder, COO, CEO-track, marketing lead, UX researcher. - Always consider outside-market personas when relevant: investors, consumers, buyers/customers, operators, compliance/risk gatekeepers, and strategic partners. - Do not flatten named people into generic roles. "Steve as Argo/Kingly COO" and "Lewis as Argo CEO-track" are different personas because their incentives, authority, risk, and objections differ. - For Argo/Kingly-style venture work, default persona pool is: - each named team member + role; - sponsor founders; - investors; - customers/buyers; - consumers/end users; - strategic partners; - risk/legal/compliance gatekeepers. If confidence is below `0.75`, ask one question: ```text Which persona base should I use: real users/buyers, internal operators, CDO-derived personality agents, or all of the above? ``` If confidence is high, continue without asking and explain the inferred persona base in `summary.md`. ## Step 2: Persona Fanout Persona Fanout turns `persona_detection.yaml` into parallel persona responses. Use it in `research`, `cdo-research`, `full`, and `interactive` modes after Step 1. Write `persona_fanout.md`: ```md # Persona Fanout ## Fanout Matrix | Persona | Source | Role | Question Asked | Output Artifact | |---|---|---|---|---| ## Cross-Persona Synthesis - Convergent needs: - Divergent needs: - Objections: - Trust signals: - Language that resonates: - UX/research implications: - Cap table/package/product implications, if relevant: ``` Fanout prompt for each persona: ```text You are {persona_id}, a {role} in this situation: {situation}. Respond from your own incentives, authority, fears, and practical constraints. Do not optimize for what the product team wants to hear. Return: 1. What you need. 2. What you distrust. 3. What would make you engage. 4. What would make you reject this. 5. What language sounds credible to you. 6. What evidence or milestone would change your mind. 7. UX/product/research implications. ``` If CDO is not requested, fanout may be run as synthetic persona responses. If CDO is requested or inferred, use CDO Persona Agent Mode below. ## CDO Persona Agent Mode When mode is `cdo-research`, each CDO agent should be a situation-specific personality/persona, not a generic expert role. The agent set should be derived from `persona_detection.yaml`. Each agent brief must include: - Persona role and authority. - Situation they are responding to. - Personality/archetype in practical UX terms, not default MBTI labels. - What they want. - What they distrust. - What evidence would change their mind. - What they would do if confused. - Output format: needs, objections, trust signals, language that resonates, failure modes, and design/research implications. Examples: - Skeptical enterprise buyer. - Time-starved operator. - Status-sensitive executive sponsor. - Domain expert who distrusts generic AI. - Novice user with high anxiety. - Compliance/risk gatekeeper. - Growth/marketing opportunist. CDO composition rule: ```yaml cdo_persona_agents: source: persona_detection.yaml composition: "one agent per candidate persona/personality type; include each named person + role, investors, and consumers/customers when relevant" synthesis_goal: "convert persona reactions into research constraints, JTBD inputs, anti-patterns, and UX risks" output_artifacts: - persona_fanout.md - cdo_insights.md - persona_source_map.yaml ``` If actual CDO/agent dispatch is unavailable, create the proposed CDO persona matrix and ask before substituting single-model synthetic responses. Do not pretend a multi-agent run occurred. ## Output Location For `agentic-research`, use the locations and artifacts in its reference: Markdown study/findings in `RUN_DIR`, runtime JSON in host-local XDG storage. The generic artifact list below applies to the other modes. Create a run folder: - `RUN_DIR=.lev/ux/{YYYYMMDD-HHMMSS}-{slug}/` Write artifacts below. If resuming, reuse the existing `RUN_DIR`. Artifacts (expected): - `domain_exploration.md` - `problem_spec.yaml` - `study_design.yaml` - `user_and_agent_research.md`