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:
- Identify the application type — web app, mobile app, desktop app, CLI tool, API, library, etc.
- Map all entry points — routes, pages, screens, commands, endpoints
- Catalog all features — what can a user actually DO? List every interactive capability.
- Identify user roles — are there different user types (admin, member, guest, free, paid)?
- Map navigation structure — how does the user move between features?
- Identify state transitions — login/logout, onboarding, setup flows, subscription changes
- Find data entities — what objects does the user create, read, update, delete?
- Detect integrations — external services, OAuth providers, APIs, webhooks
- Note error states — error boundaries, fallback UI, empty states, loading states
- 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:
- The discovery document (
docs/ux-paths/discovery.md) for context
- Its assigned topic
- Instructions to produce realistic user journey stories
Each agent must:
- Read the discovery document for app context
- Deep-dive into the codebase for their assigned topic area — read the actual components, routes, handlers, and logic
- 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:
- Read all topic files from
docs/ux-paths/topics/
- Read the discovery document for context
- Assign sequential STORY IDs across all topics (STORY-001, STORY-002, ...)
- Deduplicate — merge stories that are substantially similar
- Cross-reference — note where stories from different topics overlap (e.g., "authentication" stories connect to "onboarding" stories)
- Add a dependency graph — which stories should be run before others (e.g., "create account" before "use feature X")
- Verify coverage — check that every feature from the discovery document is exercised by at least one story
- Flag gaps — list any features or flows NOT covered by any story
- 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.
1---2name: ux-paths-23description: Generate exhaustive user journey stories by analyzing the codebase. Creates realistic UX paths (short feature exercises and long end-to-end flows) using a swarm of parallel sub-agents. Use when asked to 'create stories', 'walk the app', 'map user journeys', 'generate ux paths', 'create user flows', 'map the app', 'what can users do', 'generate test scenarios', 'create e2e stories', or 'exercise the app'.4---56# UX Paths — User Journey Story Generator78Generate 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.910## Overview1112```13User invokes /ux-paths [optional focus area]14└── Top-level agent (you — orchestrator only)15 ├── Phase 1: Discovery Agent (Explore)16 │ └── Deep codebase scan → topic list + app map17 ├── Phase 2: Story Swarm (8-12 Explore agents in parallel)18 │ ├── Agent: Authentication & Onboarding paths19 │ ├── Agent: Core Feature A paths20 │ ├── Agent: Core Feature B paths21 │ ├── Agent: Settings & Configuration paths22 │ ├── Agent: Error & Edge Case paths23 │ ├── Agent: Data Management paths24 │ ├── Agent: Navigation & Discovery paths25 │ ├── Agent: Integration & External Service paths26 │ ├── Agent: Multi-step Workflow paths27 │ ├── Agent: Power User & Advanced paths28 │ ├── Agent: First-time User / Onboarding paths29 │ └── Agent: Destructive & Cleanup paths30 └── Phase 3: Consolidation Agent (general-purpose)31 └── Merge, deduplicate, organize → final catalog32```3334---3536## Parameters3738| Parameter | Default | Notes |39|-----------|---------|-------|40| **Focus area** | Entire app | Optional `$ARGUMENTS` to scope (e.g., "authentication", "checkout flow") |41| **Output directory** | `docs/ux-paths/` | Where the final catalog and per-topic files land |42| **Depth** | `deep` | `quick` = fewer agents, shorter paths. `deep` = full swarm |4344---4546## Phase 1: Discovery4748Spawn a single **Explore sub-agent** (read-only, no worktree) to produce an application map.4950### Discovery Agent Prompt5152The discovery agent must:53541. **Identify the application type** — web app, mobile app, desktop app, CLI tool, API, library, etc.552. **Map all entry points** — routes, pages, screens, commands, endpoints563. **Catalog all features** — what can a user actually DO? List every interactive capability.574. **Identify user roles** — are there different user types (admin, member, guest, free, paid)?585. **Map navigation structure** — how does the user move between features?596. **Identify state transitions** — login/logout, onboarding, setup flows, subscription changes607. **Find data entities** — what objects does the user create, read, update, delete?618. **Detect integrations** — external services, OAuth providers, APIs, webhooks629. **Note error states** — error boundaries, fallback UI, empty states, loading states6310. **Check for feature flags / conditional UI** — features behind toggles or permissions6465The agent should search broadly across whatever framework/stack the project uses:66- **Routes / entry points**: React Router, Next.js pages/app dir, Express/Hono routes, Flask/Django URLs, SwiftUI NavigationStack, CLI command definitions, etc.67- **Page / screen components**: Whatever the UI layer is — React components, Vue views, SwiftUI views, Android Activities, CLI command handlers68- **Navigation structure**: Sidebars, tab bars, menus, breadcrumbs, command palettes, routing config69- **Forms / user input**: What data does the user provide? Forms, prompts, file pickers, CLI arguments70- **Modals / confirmations**: Dialogs, confirmation prompts, overlays, CLI interactive prompts71- **API endpoints**: REST routes, GraphQL schema, tRPC routers, gRPC services72- **Auth / guards**: Middleware, route guards, permission checks, role-based access73- **State management**: Stores, contexts, reducers, databases, config files74- **Config / feature flags**: Environment vars, feature toggles, permissions, roles75- **Read `references/path-categories.md`** from this skill's directory for the full taxonomy of categories to look for7677### Discovery Output7879The agent writes to `docs/ux-paths/discovery.md`:8081```markdown82# App Discovery: {App Name}8384## Application Type85{web app / desktop app / mobile app / CLI / API}8687## Tech Stack88{framework, router, state management, auth system}8990## User Roles91- {role 1}: {what they can do}92- {role 2}: {what they can do}9394## Feature Map95### {Feature Area 1}96- {capability 1}97- {capability 2}9899### {Feature Area 2}100- ...101102## Navigation Structure103{how users move between features}104105## Data Entities106- {entity}: create / read / update / delete107- ...108109## Integrations110- {service}: {what it does}111112## Recommended Story Topics1131. {Topic 1} — {brief rationale}1142. {Topic 2} — {brief rationale}115...116(aim for 8-12 topics that collectively cover the entire app)117```118119The **Recommended Story Topics** list is critical — it becomes the assignment list for Phase 2.120121---122123## Phase 2: Story Swarm124125After the discovery agent completes, spawn **one Explore sub-agent per topic** — all in parallel.126127### How Many Agents?128129- Use however many topics the discovery agent identified (typically 8-12)130- Each topic gets its own agent131- All agents run simultaneously132133### Story Agent Prompt Template134135Each story agent receives:1361371. The discovery document (`docs/ux-paths/discovery.md`) for context1382. Its assigned topic1393. Instructions to produce realistic user journey stories140141Each agent must:1421431. **Read the discovery document** for app context1442. **Deep-dive into the codebase** for their assigned topic area — read the actual components, routes, handlers, and logic1453. **Generate stories** — each story is a numbered sequence of concrete user actions146147### Story Format148149Each story follows this structure:150151```markdown152## STORY-{NNN}: {Descriptive Title}153154**Type**: short | medium | long155**Topic**: {assigned topic}156**Persona**: {who is doing this — new user, power user, admin, etc.}157**Goal**: {what the user is trying to accomplish}158**Preconditions**: {what state must exist before this story starts}159160### Steps1611. {User action} → {Expected result}1622. {User action} → {Expected result}1633. ...164165### Variations166- {Variation A}: {what changes and why}167- {Variation B}: {what changes and why}168169### Edge Cases170- {Edge case}: {what happens}171```172173### Story Guidelines for Each Agent174175**Short stories** (2-5 steps): Exercise a single feature in isolation.176- Log in with valid credentials177- Change a setting178- Delete an item179- Search for something180- Toggle a feature on/off181182**Medium stories** (5-15 steps): Complete a meaningful workflow.183- Sign up and configure initial settings184- Create a resource and verify it appears correctly185- Start a task, encounter an error, recover, complete the task186- Use search to find something, then take action on it187188**Long stories** (15-40 steps): Full end-to-end user journeys.189- First-time user: discover app → sign up → onboard → use core feature → customize → invite others190- Power user: log in → navigate to advanced feature → configure → execute workflow → review results → export191- Admin: manage users → configure system → handle edge case → audit activity192193**Realism rules:**194- Steps must reference actual UI elements, routes, and features found in the codebase195- Don't invent features that don't exist196- Include realistic data (not "test123" — use plausible names, emails, values)197- Consider what the user is THINKING at each step, not just clicking198- Include moments where the user might hesitate, make a mistake, or change their mind199- Reference actual button labels, menu items, and page titles from the code200201**Each agent should produce 5-15 stories** for their topic, mixing short/medium/long.202203### Story Agent Output204205Each agent writes to `docs/ux-paths/topics/{topic-slug}.md`.206207---208209## Phase 3: Consolidation210211After all story agents complete, spawn a **general-purpose sub-agent** (no worktree needed) to:2122131. **Read all topic files** from `docs/ux-paths/topics/`2142. **Read the discovery document** for context2153. **Assign sequential STORY IDs** across all topics (STORY-001, STORY-002, ...)2164. **Deduplicate** — merge stories that are substantially similar2175. **Cross-reference** — note where stories from different topics overlap (e.g., "authentication" stories connect to "onboarding" stories)2186. **Add a dependency graph** — which stories should be run before others (e.g., "create account" before "use feature X")2197. **Verify coverage** — check that every feature from the discovery document is exercised by at least one story2208. **Flag gaps** — list any features or flows NOT covered by any story2219. **Produce the final catalog**222223### Final Catalog Format224225Write to `docs/ux-paths/catalog.md`:226227```markdown228# UX Path Catalog: {App Name}229230Generated: {date}231Total Stories: {count}232Coverage: {features covered} / {total features} ({percentage})233234## Summary235236| Type | Count |237|------|-------|238| Short | {n} |239| Medium | {n} |240| Long | {n} |241242## Coverage Matrix243244| Feature Area | Stories | Gaps |245|-------------|---------|------|246| {area} | STORY-001, STORY-005, STORY-012 | {any uncovered aspects} |247| ... | ... | ... |248249## Story Dependency Graph250251```text252STORY-001 (Create Account)253├── STORY-005 (Configure Settings)254│ └── STORY-012 (Advanced Configuration)255├── STORY-008 (Create First Project)256│ ├── STORY-015 (Collaborate on Project)257│ └── STORY-020 (Export Project)258└── STORY-003 (Browse as New User)259```260261## All Stories262263### Authentication & Onboarding264{stories from this topic}265266### {Next Topic}267{stories from this topic}268269...270271## Gaps & Recommendations272- {feature/flow not covered and why}273- {suggested additional stories}274```275276---277278## Execution Checklist279280When invoked, follow these steps exactly:281282### Step 0: Setup283284```bash285mkdir -p docs/ux-paths/topics286```287288If `$ARGUMENTS` contains a focus area, note it — the discovery agent should prioritize that area but still map the full app for context.289290### Step 1: Spawn Discovery Agent291292Spawn 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.293294### Step 2: Spawn Story Swarm295296Read 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:297- The discovery document path298- Its assigned topic name299- The output path: `docs/ux-paths/topics/{topic-slug}.md`300- The story format and guidelines from Phase 2 above301302### Step 3: Wait for Swarm Completion303304All agents must finish before consolidation. As each completes, note the summary.305306### Step 4: Spawn Consolidation Agent307308Spawn one general-purpose sub-agent with the Phase 3 prompt. Wait for completion.309310### Step 5: Report to User311312Print a summary:313- Total stories generated314- Breakdown by type (short/medium/long)315- Coverage percentage316- Any notable gaps317- Path to the catalog: `docs/ux-paths/catalog.md`318319---320321## Tips322323- **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.324- **Don't over-constrain topics.** Let the discovery agent determine natural topic boundaries based on the actual codebase, not a predetermined list.325- **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."326- **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.327- **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.328- **Re-run periodically.** As the app evolves, re-run this skill to catch new features and deprecated flows. The catalog is a living document.