ux-paths

UX Paths — User Journey Story Generator

Generate an exhaustive, realistic catalog of user journeys through any application by analyzing its codebase. Produces short stories (exercise one feature) and long stories (complete multi-step workflows) that reflect how real users would actually use the app.

Overview

User invokes /ux-paths [optional focus area]
└── Top-level agent (you — orchestrator only)
    ├── Phase 1: Discovery Agent (Explore)
    │   └── Deep codebase scan → topic list + app map
    ├── Phase 2: Story Swarm (8-12 Explore agents in parallel)
    │   ├── Agent: Authentication & Onboarding paths
    │   ├── Agent: Core Feature A paths
    │   ├── Agent: Core Feature B paths
    │   ├── Agent: Settings & Configuration paths
    │   ├── Agent: Error & Edge Case paths
    │   ├── Agent: Data Management paths
    │   ├── Agent: Navigation & Discovery paths
    │   ├── Agent: Integration & External Service paths
    │   ├── Agent: Multi-step Workflow paths
    │   ├── Agent: Power User & Advanced paths
    │   ├── Agent: First-time User / Onboarding paths
    │   └── Agent: Destructive & Cleanup paths
    └── Phase 3: Consolidation Agent (general-purpose)
        └── Merge, deduplicate, organize → final catalog

---

Parameters

Parameter	Default	Notes
Focus area	Entire app	Optional $ARGUMENTS to scope (e.g., "authentication", "checkout flow")
Output directory	docs/ux-paths/	Where the final catalog and per-topic files land
Depth	deep	quick = fewer agents, shorter paths. deep = full swarm

---

Phase 1: Discovery

Spawn a single Explore sub-agent (read-only, no worktree) to produce an application map.

Discovery Agent Prompt

The discovery agent must:

1. Identify the application type — web app, mobile app, desktop app, CLI tool, API, library, etc.
2. Map all entry points — routes, pages, screens, commands, endpoints
3. Catalog all features — what can a user actually DO? List every interactive capability.
4. Identify user roles — are there different user types (admin, member, guest, free, paid)?
5. Map navigation structure — how does the user move between features?
6. Identify state transitions — login/logout, onboarding, setup flows, subscription changes
7. Find data entities — what objects does the user create, read, update, delete?
8. Detect integrations — external services, OAuth providers, APIs, webhooks
9. Note error states — error boundaries, fallback UI, empty states, loading states
10. Check for feature flags / conditional UI — features behind toggles or permissions

The agent should search broadly across whatever framework/stack the project uses:

• Routes / entry points: React Router, Next.js pages/app dir, Express/Hono routes, Flask/Django URLs, SwiftUI NavigationStack, CLI command definitions, etc.
• Page / screen components: Whatever the UI layer is — React components, Vue views, SwiftUI views, Android Activities, CLI command handlers
• Navigation structure: Sidebars, tab bars, menus, breadcrumbs, command palettes, routing config
• Forms / user input: What data does the user provide? Forms, prompts, file pickers, CLI arguments
• Modals / confirmations: Dialogs, confirmation prompts, overlays, CLI interactive prompts
• API endpoints: REST routes, GraphQL schema, tRPC routers, gRPC services
• Auth / guards: Middleware, route guards, permission checks, role-based access
• State management: Stores, contexts, reducers, databases, config files
• Config / feature flags: Environment vars, feature toggles, permissions, roles
• Read references/path-categories.md from this skill's directory for the full taxonomy of categories to look for

Discovery Output

The agent writes to docs/ux-paths/discovery.md:

# App Discovery: {App Name}

## Application Type
{web app / desktop app / mobile app / CLI / API}

## Tech Stack
{framework, router, state management, auth system}

## User Roles
- {role 1}: {what they can do}
- {role 2}: {what they can do}

## Feature Map
### {Feature Area 1}
- {capability 1}
- {capability 2}

### {Feature Area 2}
- ...

## Navigation Structure
{how users move between features}

## Data Entities
- {entity}: create / read / update / delete
- ...

## Integrations
- {service}: {what it does}

## Recommended Story Topics
1. {Topic 1} — {brief rationale}
2. {Topic 2} — {brief rationale}
...
(aim for 8-12 topics that collectively cover the entire app)

The Recommended Story Topics list is critical — it becomes the assignment list for Phase 2.

---

Phase 2: Story Swarm

After the discovery agent completes, spawn one Explore sub-agent per topic — all in parallel.

How Many Agents?

• Use however many topics the discovery agent identified (typically 8-12)
• Each topic gets its own agent
• All agents run simultaneously

Story Agent Prompt Template

Each story agent receives:

1. The discovery document (docs/ux-paths/discovery.md) for context
2. Its assigned topic
3. Instructions to produce realistic user journey stories

Each agent must:

1. Read the discovery document for app context
2. Deep-dive into the codebase for their assigned topic area — read the actual components, routes, handlers, and logic
3. Generate stories — each story is a numbered sequence of concrete user actions

Story Format

Each story follows this structure:

## STORY-{NNN}: {Descriptive Title}

**Type**: short | medium | long
**Topic**: {assigned topic}
**Persona**: {who is doing this — new user, power user, admin, etc.}
**Goal**: {what the user is trying to accomplish}
**Preconditions**: {what state must exist before this story starts}

### Steps
1. {User action} → {Expected result}
2. {User action} → {Expected result}
3. ...

### Variations
- {Variation A}: {what changes and why}
- {Variation B}: {what changes and why}

### Edge Cases
- {Edge case}: {what happens}

Story Guidelines for Each Agent

Short stories (2-5 steps): Exercise a single feature in isolation.

• Log in with valid credentials
• Change a setting
• Delete an item
• Search for something
• Toggle a feature on/off

Medium stories (5-15 steps): Complete a meaningful workflow.

• Sign up and configure initial settings
• Create a resource and verify it appears correctly
• Start a task, encounter an error, recover, complete the task
• Use search to find something, then take action on it

Long stories (15-40 steps): Full end-to-end user journeys.

• First-time user: discover app → sign up → onboard → use core feature → customize → invite others
• Power user: log in → navigate to advanced feature → configure → execute workflow → review results → export
• Admin: manage users → configure system → handle edge case → audit activity

Realism rules:

• Steps must reference actual UI elements, routes, and features found in the codebase
• Don't invent features that don't exist
• Include realistic data (not "test123" — use plausible names, emails, values)
• Consider what the user is THINKING at each step, not just clicking
• Include moments where the user might hesitate, make a mistake, or change their mind
• Reference actual button labels, menu items, and page titles from the code

Each agent should produce 5-15 stories for their topic, mixing short/medium/long.

Story Agent Output

Each agent writes to docs/ux-paths/topics/{topic-slug}.md.

---

Phase 3: Consolidation

After all story agents complete, spawn a general-purpose sub-agent (no worktree needed) to:

1. Read all topic files from docs/ux-paths/topics/
2. Read the discovery document for context
3. Assign sequential STORY IDs across all topics (STORY-001, STORY-002, ...)
4. Deduplicate — merge stories that are substantially similar
5. Cross-reference — note where stories from different topics overlap (e.g., "authentication" stories connect to "onboarding" stories)
6. Add a dependency graph — which stories should be run before others (e.g., "create account" before "use feature X")
7. Verify coverage — check that every feature from the discovery document is exercised by at least one story
8. Flag gaps — list any features or flows NOT covered by any story
9. Produce the final catalog

Final Catalog Format

Write to docs/ux-paths/catalog.md:

# UX Path Catalog: {App Name}

Generated: {date}
Total Stories: {count}
Coverage: {features covered} / {total features} ({percentage})

## Summary

| Type | Count |
|------|-------|
| Short | {n} |
| Medium | {n} |
| Long | {n} |

## Coverage Matrix

| Feature Area | Stories | Gaps |
|-------------|---------|------|
| {area} | STORY-001, STORY-005, STORY-012 | {any uncovered aspects} |
| ... | ... | ... |

## Story Dependency Graph

```text
STORY-001 (Create Account)
├── STORY-005 (Configure Settings)
│   └── STORY-012 (Advanced Configuration)
├── STORY-008 (Create First Project)
│   ├── STORY-015 (Collaborate on Project)
│   └── STORY-020 (Export Project)
└── STORY-003 (Browse as New User)

All Stories

Authentication & Onboarding

{stories from this topic}

{Next Topic}

{stories from this topic}

...

Gaps & Recommendations

• {feature/flow not covered and why}
• {suggested additional stories}

---

## Execution Checklist

When invoked, follow these steps exactly:

### Step 0: Setup

```bash
mkdir -p docs/ux-paths/topics

If $ARGUMENTS contains a focus area, note it — the discovery agent should prioritize that area but still map the full app for context.

Step 1: Spawn Discovery Agent

Spawn one Explore sub-agent with the Phase 1 prompt above. Wait for it to complete. Read the output summary — you need the topic list for Phase 2.

Step 2: Spawn Story Swarm

Read the recommended topics from docs/ux-paths/discovery.md. For each topic, spawn an Explore sub-agent — all in parallel in a single message. Each agent gets:

• The discovery document path
• Its assigned topic name
• The output path: docs/ux-paths/topics/{topic-slug}.md
• The story format and guidelines from Phase 2 above

Step 3: Wait for Swarm Completion

All agents must finish before consolidation. As each completes, note the summary.

Step 4: Spawn Consolidation Agent

Spawn one general-purpose sub-agent with the Phase 3 prompt. Wait for completion.

Step 5: Report to User

Print a summary:

• Total stories generated
• Breakdown by type (short/medium/long)
• Coverage percentage
• Any notable gaps
• Path to the catalog: docs/ux-paths/catalog.md

---

Tips

• The discovery phase is the foundation. If the discovery agent misses a major feature area, the whole catalog will have gaps. Better to spend more time in Phase 1 than to rush into Phase 2.
• Don't over-constrain topics. Let the discovery agent determine natural topic boundaries based on the actual codebase, not a predetermined list.
• Stories should be opinionated. A good story has a specific persona with a specific goal — not "a user does some things." Bad: "User clicks settings." Good: "Maria, a team lead, needs to add her 3 new hires to the project before standup tomorrow."
• Variations matter. The happy path is one story. The error path, the edge case, the mobile viewport, the slow connection — these are all variations worth capturing.
• Cross-topic stories are valuable. Some of the best test scenarios span multiple feature areas. The consolidation agent should explicitly look for and create these.
• Re-run periodically. As the app evolves, re-run this skill to catch new features and deprecated flows. The catalog is a living document.