detect-ux

Repo-driven UX audit with journeys, pain-points, and heuristic-based findings.

Context Files

• $JAAN_LEARN_DIR/jaan-to-detect-ux.learn.md - Past lessons (loaded in Pre-Execution)
• $JAAN_CONTEXT_DIR/tech.md - Tech stack (for framework-aware route detection)
• $JAAN_TEMPLATES_DIR/jaan-to-detect-ux.template.md - Output template
• ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md - Language resolution protocol

Output path: $JAAN_OUTPUTS_DIR/detect/ux/ — flat files, overwritten each run (no IDs).

Input

Arguments: $ARGUMENTS — parsed in Step 0.0. Repository path and mode determined there.

Pre-Execution Protocol

MANDATORY — Read and execute ALL steps in: ${CLAUDE_PLUGIN_ROOT}/docs/extending/pre-execution-protocol.md Skill name: detect-ux Execute: Step 0 (Init Guard) → A (Load Lessons) → B (Resolve Template) → C (Offer Template Seeding)

Language Settings

Read and apply language protocol: ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md Override field for this skill: language_detect-ux

Standards Reference

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/detect-shared-reference.md for Evidence Format (SARIF), Evidence ID Generation, Confidence Levels, Frontmatter Schema, Platform Detection, Document Structure, and Codebase Content Safety.

This skill's namespace: E-UX-* (e.g., E-UX-001, E-UX-WEB-001) Tool name in frontmatter: detect-ux

PHASE 1: Detection (Read-Only)

Step 0.0: Parse Arguments

Arguments: $ARGUMENTS

Mode determination:

• If $ARGUMENTS contains --full as a standalone token → set run_depth = "full"
• Otherwise → set run_depth = "light"

Strip --full token from arguments. Set repo_path to remaining arguments (or current working directory if empty).

Thinking Mode

If run_depth == "full": ultrathink If run_depth == "light": megathink

Use extended reasoning for:

• Route/screen mapping from framework-specific patterns
• Journey flow construction from navigation patterns
• Nielsen heuristic assessment from code signals
• Pain-point inference from error handling patterns

Step 0: Detect Platforms

Purpose: Auto-detect platform structure and check for UI/TUI presence before UX analysis.

Use Glob and Bash to identify platform folders (same patterns as detect-dev - see detect-dev Step 0 for full platform patterns and disambiguation rules).

Platform Detection

1. Check for monorepo markers: pnpm-workspace.yaml, lerna.json, nx.json, turbo.json
2. List top-level directories: Exclude node_modules, .git, build outputs
3. Match against platform patterns: Apply disambiguation rules
4. Handle detection results:
   • No platforms → Single-platform: platforms = [{ name: 'all', path: '.' }]
   • Platforms detected → Multi-platform: Ask user to select all or specific platforms

UI/TUI Presence Check (UX Audit Applicability)

For each platform, check for UI or TUI (terminal UI) indicators:

# Check for UI component files
ui_files=$(find {platform.path} -type f \( -name "*.jsx" -o -name "*.tsx" -o -name "*.vue" -o -name "*.svelte" \) 2>/dev/null | head -n 1)

# Check for TUI libraries (blessed, ink, bubbletea, etc.)
tui_detected=$(grep -r "blessed\|ink\|bubbletea\|charm" {platform.path}/package.json {platform.path}/go.mod 2>/dev/null)

if [ -z "$ui_files" ] && [ -z "$tui_detected" ]; then
  # No UI/TUI files detected - UX analysis not applicable
  platform_has_ui = false
else
  platform_has_ui = true
fi

Platform applicability:

Analysis Loop

For each platform in platforms:

1. Set current_platform = platform.name
2. Set base_path = platform.path
3. Check UI/TUI presence using the check above
4. If platform_has_ui == false and platform is backend/cli:
   • Skip Steps 1-7 (detection steps)
   • Go directly to Step 8 with "Not Applicable" findings
5. If platform_has_ui == true or platform is expected to have UI:
   • Run detection steps per run_depth:
     • If run_depth == "full": Run Steps 1-7 scoped to base_path
     • If run_depth == "light": Run Steps 1 and 4 only scoped to base_path (skip Steps 2, 3, 5, 6, 7)
6. Use platform-specific output paths in Step 9

"Not Applicable" Findings Structure:

When a platform has no UI/TUI and UX analysis is not applicable, create minimal output files with this finding:

---
findings_summary:
  critical: 0
  high: 0
  medium: 0
  low: 0
  informational: 1
overall_score: 10.0  # Perfect score (nothing to assess)
---

## Executive Summary

No UI/TUI detected for platform '{platform}'. UX audit (route mapping, user flows, heuristic assessment) is not applicable to this platform type.

## Findings

### E-UX-{PLATFORM}-001: No UI/TUI Detected

**Severity**: Informational
**Confidence**: Confirmed (1.0)

**Description**: Platform '{platform}' does not contain UI components (.jsx, .tsx, .vue, .svelte) or TUI libraries. UX analysis (journeys, personas, heuristics, accessibility) is not applicable to this platform type.

**Evidence**:
```yaml
evidence:
  id: E-UX-{PLATFORM}-001
  type: absence
  confidence: 1.0
  method: glob-pattern-match
  description: "No UI/TUI files found in {platform.path}"

**Note**: If single-platform mode (`platform.name == 'all'`), output paths have NO suffix. If multi-platform mode, output paths include `-{platform}` suffix.

**Precedence**: N/A handling (platform_has_ui checks) always takes priority over run_depth gates. If `platform_has_ui == false`, skip ALL detection steps regardless of run_depth.

## Step 1: Route / Screen Mapping

Detect framework and extract routes:

### Framework-Specific Route Extraction

**React Router**:
- Grep: `useRoutes(`, `<Route`, `<Outlet`, `createBrowserRouter`
- Extract: path, element/component, nested routes, layout routes

**Next.js**:
- Glob: `app/**/page.{tsx,jsx,ts,js}` — app router pages
- Glob: `pages/**/*.{tsx,jsx,ts,js}` — pages router
- Detect dynamic routes: `[slug]`, `[...catchAll]`, `[[...optional]]`
- Detect route groups: `(group)/`
- Detect layouts: `layout.{tsx,jsx}`

**Vue Router**:
- Grep: `routes` array definitions, `<RouterView`, `<router-view`
- Glob: `**/router/**/*.{ts,js}` — router config files

**Angular**:
- Glob: `**/*routing.module.ts`, `**/*-routes.ts`
- Grep: `canActivate`, `canDeactivate` guards
- Extract: path, component, guards, lazy-loaded modules

**Express / API backends**:
- Grep: `app.get(`, `app.post(`, `app.put(`, `app.delete(`
- Grep: `router.get(`, `router.post(`, `router.put(`
- Grep: `@Get(`, `@Post(` — NestJS decorators

### Screen Inventory

For each route/page, extract:
- Route path and name
- Component file location
- Auth requirement (guards, middleware, redirect patterns)
- Layout parent
- Query parameters / dynamic segments

**If `run_depth == "light"`:** Skip Steps 2-3. Proceed to Step 4 (Map User Flows).

## Step 2: Infer User Personas

From route structure and component analysis, infer personas:

- **Authenticated vs unauthenticated** routes -> at least 2 persona types
- **Admin/dashboard routes** -> admin/power user persona
- **Onboarding flows** -> new user persona
- **API-only routes** -> developer/integrator persona
- **Settings/profile routes** -> returning user persona

Mark all personas as **Tentative** confidence — these are inferred from code structure, not validated user research.

## Step 3: Infer Jobs-to-be-Done (JTBD)

From features and flows detected:
- Group related routes into functional areas (auth, billing, content, settings)
- For each area, construct JTBD statement: "When {situation}, I want to {motivation}, so I can {expected outcome}"
- Link to route evidence

Mark all JTBD as **Tentative** — inferred from code, not user research.

## Step 4: Map User Flows

Trace navigation paths through the application:

- Detect navigation components: `<Link`, `<NavLink`, `useNavigate`, `router.push`
- Map which pages link to which other pages
- Identify entry points (landing, login, deep links)
- Identify exit points (logout, external links)
- Detect multi-step flows (wizards, checkout, onboarding)

For multi-step flows, construct Mermaid flow diagrams:
```mermaid
graph LR
    A[Cart] --> B[Shipping] --> C[Payment] --> D[Confirmation]

If run_depth == "light": Skip Steps 5-7. Proceed directly to Step 8 (Present Detection Summary).

Step 5: Detect Pain Points

Scan for UX friction signals:

Error Handling Patterns

• Grep: <ErrorBoundary, ErrorFallback, errorElement
• Check for error states in forms: validation messages, inline errors
• Look for generic error pages vs contextual error handling
• Detect retry patterns: retry, refetch, onError

Loading Patterns

• Grep: isLoading, isPending, <Skeleton, <Spinner, <Suspense
• Check for loading states on data-fetching pages
• Detect missing loading states (data fetch without loading indicator)

Form Complexity

• Count form fields per form component
• Detect multi-step forms vs single-page forms
• Check for form validation: validate, yup, zod, formik
• Look for autosave patterns

Dead Ends

• Routes without navigation back
• Error states without recovery actions
• Empty states without CTAs

Step 6: Nielsen's 10 Heuristics Assessment

Evaluate each heuristic from code evidence:

For each heuristic:

• Scan for positive signals (good practices found)
• Scan for negative signals (violations found)
• Rate: Strong / Adequate / Weak / Unknown
• Cite evidence for each rating

Important: Missing code evidence does NOT equal a violation. Mark as "Unknown" when evidence is insufficient.

Step 7: Accessibility Assessment (Repo-Scoped)

Scope: Code-level only. Cannot make runtime behavior claims.

• Grep: ARIA attributes (aria-label, aria-describedby, aria-live, role=)
• Check semantic HTML usage
• Detect keyboard navigation patterns: onKeyDown, tabIndex, focus management
• Look for skip links: #main-content, skipToContent
• Check for a11y testing: jest-axe, @axe-core, cypress-axe, pa11y
• Check for reduced motion: prefers-reduced-motion

Mark findings as "Unknown" for runtime behavior that can't be verified from code.

HARD STOP — Detection Summary & User Approval

Step 8: Present Detection Summary

If run_depth == "light":

UX DETECTION COMPLETE (Light Mode)
-------------------------------------

PLATFORM: {platform_name or 'all'}
UI/TUI PRESENCE: {Yes/No} {if No, show "(Not Applicable)"}

ROUTES/SCREENS: {n} routes mapped
USER FLOWS: {n} flows mapped

SEVERITY SUMMARY
  Critical: {n}  |  High: {n}  |  Medium: {n}  |  Low: {n}  |  Info: {n}

OVERALL SCORE: {score}/10

OUTPUT FILE (1):
  $JAAN_OUTPUTS_DIR/detect/ux/summary{-platform}.md

Note: Run with --full for persona inference, JTBD mapping, pain point detection,
Nielsen heuristic assessment, and accessibility audit (7 output files).

"Proceed with writing summary to $JAAN_OUTPUTS_DIR/detect/ux/? [y/n]"

If run_depth == "full":

UX DETECTION COMPLETE
----------------------

PLATFORM: {platform_name or 'all'}
UI/TUI PRESENCE: {Yes/No} {if No, show "(Not Applicable)"}

ROUTES/SCREENS: {n} routes mapped
PERSONAS (inferred): {n} personas
JTBD (inferred): {n} jobs-to-be-done
USER FLOWS: {n} flows mapped

NIELSEN HEURISTICS
  Strong:   {n}/10
  Adequate: {n}/10
  Weak:     {n}/10
  Unknown:  {n}/10

PAIN POINTS: {n} detected
ACCESSIBILITY: {n} findings (repo-scoped)
UX GAPS: {n} identified

SEVERITY SUMMARY
  Critical: {n}  |  High: {n}  |  Medium: {n}  |  Low: {n}  |  Info: {n}

OVERALL SCORE: {score}/10

OUTPUT FILES (7):
  $JAAN_OUTPUTS_DIR/detect/ux/personas{-platform}.md       - Inferred personas
  $JAAN_OUTPUTS_DIR/detect/ux/jtbd{-platform}.md           - Jobs-to-be-done
  $JAAN_OUTPUTS_DIR/detect/ux/flows{-platform}.md          - User flows with diagrams
  $JAAN_OUTPUTS_DIR/detect/ux/pain-points{-platform}.md    - UX friction and pain points
  $JAAN_OUTPUTS_DIR/detect/ux/heuristics{-platform}.md     - Nielsen 10 heuristics assessment
  $JAAN_OUTPUTS_DIR/detect/ux/accessibility{-platform}.md  - A11y findings (repo-scoped)
  $JAAN_OUTPUTS_DIR/detect/ux/gaps{-platform}.md           - UX gaps and recommendations

Note: {-platform} suffix only if multi-platform mode (e.g., -web, -mobile). Single-platform mode has no suffix.
      If UI/TUI presence = No, files contain "Not Applicable" findings.

"Proceed with writing 7 output files to $JAAN_OUTPUTS_DIR/detect/ux/? [y/n]"

Do NOT proceed to Phase 2 without explicit approval.

PHASE 2: Write Output Files

Step 9: Write to $JAAN_OUTPUTS_DIR/detect/ux/

Create directory $JAAN_OUTPUTS_DIR/detect/ux/ if it does not exist.

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/detect-shared-reference.md sections "Output Path Logic" and "Stale File Cleanup" for platform-specific suffix convention and run_depth cleanup rules.

If run_depth == "light": Write Single Summary File

Write one file: $JAAN_OUTPUTS_DIR/detect/ux/summary{suffix}.md

Contents:

1. Universal YAML frontmatter with platform field, findings_summary, and overall_score
2. Executive Summary — BLUF of UX findings
3. Screen Inventory — routes/screens mapped with auth classification (from Step 1)
4. Key User Flows — top flows as Mermaid diagrams (from Step 4)
5. Top Findings — up to 5 highest-severity findings with evidence blocks
6. "Run with --full for persona inference, JTBD mapping, pain point detection, Nielsen heuristic assessment, and accessibility audit (7 output files)."

If run_depth == "full": Write 7 Output Files

Write 7 output files:

Note: {suffix} is empty for single-platform mode, or -{platform} for multi-platform mode.

If UI/TUI presence = No (from Step 0 check), write minimal "Not Applicable" files with:

• Frontmatter: findings_summary.informational: 1, overall_score: 10.0
• Single finding: "E-UX-{PLATFORM}-001: No UI/TUI Detected" (severity: informational)

Each file MUST include:

1. Universal YAML frontmatter with platform field and findings_summary/overall_score
2. Executive Summary
3. Scope and Methodology
4. Findings with evidence blocks (using E-UX-{PLATFORM}-NNN or E-UX-NNN IDs)
5. Recommendations

Step 9a: Seed Reconciliation

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/seed-reconciliation-reference.md for comparison rules, discrepancy format, and auto-update protocol.

1. Read domain-relevant seed files: $JAAN_CONTEXT_DIR/tone-of-voice.template.md
2. Compare detection results against seed content (UX tone patterns, error message guidelines, empty state copy)
3. If discrepancies found:
   • Display discrepancy table to user
   • Offer auto-updates for non-destructive changes: [y/n]
   • Suggest /jaan-to:learn-add commands for patterns worth documenting
4. If no discrepancies: display "Seed files are aligned with detection results."

Step 10: Capture Feedback

"Any feedback on the UX audit? [y/n]"

If yes:

• Run /jaan-to:learn-add detect-ux "{feedback}"

Skill Alignment

• Two-phase workflow with HARD STOP for human approval
• Evidence-based findings with confidence scoring
• Fork-isolated execution (context: fork)
• Output to standardized $JAAN_OUTPUTS_DIR path

Definition of Done

If run_depth == "light":

• Single summary file written to $JAAN_OUTPUTS_DIR/detect/ux/summary{suffix}.md
• Universal YAML frontmatter with overall_score
• Screen inventory and user flows included with evidence blocks
• "--full" upsell note included
• User approved output

If run_depth == "full":

• All 7 output files written to $JAAN_OUTPUTS_DIR/detect/ux/
• Universal YAML frontmatter with platform field in every file
• Every finding has evidence block with correct ID format (E-UX-NNN for single-platform, E-UX-{PLATFORM}-NNN for multi-platform)
• Routes/screens mapped from framework-specific patterns
• Personas and JTBD marked as Tentative (inferred)
• Nielsen heuristics assessed with code evidence
• Accessibility findings scoped to repo (no runtime claims)
• Mermaid flow diagrams for multi-step flows
• Confidence scores assigned to all findings
• Output filenames match platform suffix convention (no suffix for single-platform, -{platform} suffix for multi-platform)
• If no UI/TUI detected for platform, minimal "Not Applicable" files created with informational findings
• User approved output
• Seed reconciliation check performed (discrepancies reported or alignment confirmed)