---
name: kodadocs-user-journeys
description: "Identify user flows from route structure and navigation links, then generate multi-step journey guides with ordered screenshots."
---

# User Journey Documentation

## Overview

This skill generates structured, multi-step user journey documentation by analyzing an application's route structure, navigation links, and page-to-page transitions. It identifies common flows (onboarding, core workflows, settings management), groups routes into logical journeys, and produces "How to" guides with numbered steps, screenshot callouts, and decision-point branching. The output integrates into your KodaDocs VitePress site as a dedicated journeys section alongside regular route-level documentation.

Use this skill when:
- You want task-oriented documentation ("How to create a project") rather than page-level docs
- Your application has multi-step workflows that span several pages
- You want onboarding guides that walk new users through initial setup
- You need to document branching flows where user choices lead to different paths
- You want to supplement auto-generated route docs with guided walkthroughs

## Prerequisites

Before running this skill, ensure the following:

1. **Project codebase:** The project directory must contain source code with route definitions and page components.
2. **Application running:** The application must be accessible at a URL for screenshot capture and DOM element extraction.
3. **KodaDocs MCP tools available:** The `mcp__kodadocs__*` tools must be accessible.
4. **KodaDocs manifest (optional):** If integrating with an existing doc site, a previous pipeline run should exist (`.kodadocs/run_manifest.json`).

## Workflow

### Step 1: Discover Routes and Analyze Codebase

Gather the foundational data: all application routes, code structure, and navigation relationships.

**Run route discovery:**
```
Call mcp__kodadocs__discover_routes with:
  project_path: "<project-root>"
  app_url: "<running application URL>"
```

Extract `discovered_routes`, `route_metadata`, `detected_services`, and `ui_components` from the response.

**Run codebase analysis:**
```
Call mcp__kodadocs__analyze_codebase with:
  project_path: "<project-root>"
  discovered_routes: [<routes from discovery>]
```

Extract `code_chunks`, `data_models`, and `error_patterns` from the response.

**Detect the framework:**
```
Call mcp__kodadocs__detect_framework with:
  project_path: "<project-root>"
```

The framework type influences how navigation links are structured (Next.js `<Link>`, SvelteKit `<a>`, React Router `<Link>`, etc.).

### Step 2: Capture Screenshots and Extract DOM Elements

Capture all route screenshots and extract interactive DOM elements to understand page-to-page navigation.

```
Call mcp__kodadocs__capture_screenshots with:
  routes: [<all discovered routes>]
  app_url: "<running application URL>"
  auth: <auth config if the app requires login, or null>
  output_dir: "<project-root>/.kodadocs/screenshots"
  blur_pii: true
```

Extract `screenshots` (route to file path mapping) and `dom_elements` (route to interactive element list). Each DOM element includes `role`, `name`, and `bounds` (x, y, width, height). Link elements also include the target URL.

**Annotate screenshots:**
```
Call mcp__kodadocs__annotate_screenshots with:
  screenshots_dir: "<project-root>/.kodadocs/screenshots"
  dom_elements: <dom_elements from capture>
```

### Step 3: Build the Navigation Graph

Construct a directed graph of page-to-page transitions from DOM elements and source code.

**Extract navigation links from DOM elements:**

| Element Type | Detection | Significance |
|-------------|-----------|--------------|
| Internal links | `<a href="/...">`, `<Link to="/...">` | Direct page-to-page transition |
| Navigation menus | Elements within `<nav>`, role="navigation" | Global navigation structure |
| Buttons with navigation | `<button>` near `router.push`, `navigate()` | Programmatic navigation |
| Form submissions | `<form action="/...">` | Flow progression |
| Stepper/wizard | Numbered steps with next/back buttons | Multi-step flow indicators |

**Build the adjacency list** by recording all outgoing internal links per route.

**Supplement with source code analysis** for programmatic redirects not visible in the DOM:

| Framework | Patterns |
|-----------|----------|
| Next.js | `router.push("/...")`, `router.replace("/...")`, `redirect("/...")`, `<Link href="/...">` |
| SvelteKit | `goto("/...")`, `<a href="/...">` |
| React Router | `navigate("/...")`, `<Navigate to="/..."/>`, `<Link to="/...">` |
| Vue Router | `router.push("/...")`, `<router-link to="/...">` |
| Generic | `window.location.href = "/..."`, `location.assign("/...")` |

Note whether each programmatic navigation is conditional (inside an `if` block, after form validation).

**Identify entry points:**
1. Routes with no incoming edges in the graph (landing pages)
2. Routes behind auth guards that redirect unauthenticated users (login page)
3. Routes referenced in the application's root redirect or home configuration
4. The root route `/` is always an entry point

### Step 4: Identify Journey Patterns

Analyze the navigation graph to detect common user journey patterns using the app type classification and pattern tables below.

**Universal journey patterns (all app types):**

| Pattern | Detection Signals | Example Flow |
|---------|------------------|--------------|
| Onboarding | Sequential routes with "signup", "setup", "welcome", "onboard"; stepper UI | `/signup` -> `/verify-email` -> `/setup-profile` -> `/dashboard` |
| Authentication | Routes with "login", "signup", "forgot-password", "reset-password" | `/login` -> `/forgot-password` -> `/reset-password` -> `/login` |
| Settings management | Routes under `/settings/*` or `/account/*` | `/settings` -> `/settings/profile` -> `/settings/billing` |
| Error recovery | Routes with "error", "404"; retry buttons | `/page` -> `/error` -> `/page` (retry) |

**SaaS-specific patterns:**

| Pattern | Detection Signals | Example Flow |
|---------|------------------|--------------|
| Resource creation | Routes with "new", "create"; form -> detail redirect | `/projects` -> `/projects/new` -> `/projects/:id` |
| Team management | Routes with "team", "members", "invite" | `/team` -> `/team/invite` -> `/team/members` |
| Billing/upgrade | Routes with "billing", "pricing", "checkout"; Stripe signals | `/billing` -> `/pricing` -> `/checkout` -> `/billing` |
| Resource CRUD | List -> Detail -> Edit pattern with `:id` params | `/items` -> `/items/:id` -> `/items/:id/edit` |

**E-commerce-specific patterns:**

| Pattern | Detection Signals | Example Flow |
|---------|------------------|--------------|
| Product browsing | Routes with "products", "catalog", "category" | `/products` -> `/products/:category` -> `/products/:id` |
| Cart and checkout | Routes with "cart", "checkout", "payment", "order" | `/products/:id` -> `/cart` -> `/checkout` -> `/order-confirmation` |
| Order tracking | Routes with "orders", "tracking" | `/orders` -> `/orders/:id` -> `/orders/:id/tracking` |

**Developer tool-specific patterns:**

| Pattern | Detection Signals | Example Flow |
|---------|------------------|--------------|
| API key management | Routes with "keys", "tokens", "credentials" | `/settings/api-keys` -> `/settings/api-keys/new` -> `/settings/api-keys` |
| Integration setup | Routes with "integrations", "connect", "webhooks" | `/integrations` -> `/integrations/:provider/connect` -> `/integrations/:provider/configure` |
| Deployment/publish | Routes with "deploy", "publish", "release" | `/projects/:id` -> `/projects/:id/deploy` -> `/projects/:id/deployments/:id` |

**Journey extraction algorithm:**

1. Start from each entry point. Perform depth-first traversal, recording the path.
2. A journey ends when the path reaches a terminal node, revisits a node, or reaches a destination page (dashboard, confirmation).
3. Prune journeys with fewer than 2 steps.
4. Merge overlapping journeys that share a common prefix.
5. Name each journey based on the matched pattern.

### Step 5: Accept Custom Journey Definitions

Present auto-detected journeys to the user and ask for input:

```
Detected user journeys:
  1. Onboarding: /signup -> /verify-email -> /setup-profile -> /dashboard
  2. Project creation: /dashboard -> /projects -> /projects/new -> /projects/:id
  3. Settings management: /dashboard -> /settings -> /settings/profile

Would you like to:
  (a) Generate documentation for all detected journeys
  (b) Select specific journeys to document
  (c) Add custom journeys
  (d) Modify a detected journey
```

Accept custom journeys as structured input (`Journey name: "...", Routes: /a -> /b -> /c`) or natural language. Match route names against discovered routes; warn if a route does not exist and suggest the closest match.

**Merging rules:** If a custom journey overlaps with a detected one (2+ shared sequential routes), ask whether to merge or keep separate. If a specified link does not exist in the navigation graph, warn and document manual navigation between those routes.

### Step 6: Generate Per-Step Screenshots

For each step in each journey, create a focused annotated screenshot highlighting only the element the user interacts with to proceed.

```
Call mcp__kodadocs__annotate_screenshots with:
  screenshots_dir: "<project-root>/.kodadocs/screenshots"
  dom_elements: {
    "<route>": [<only the element(s) relevant to this journey step>]
  }
  brand_color: "<brand color>"
```

For dynamic routes (e.g., `/projects/:id`), note in the article that specific content will vary. For routes not yet captured (modals, intermediate states), attempt a targeted `capture_screenshots` call; if it fails, note "[Screenshot not available for this step]" in the article.

### Step 7: Generate Journey Articles

Produce a "How to" article for each journey with numbered steps, screenshot references, and decision points.

**Journey article template:**

```markdown
# How to <Journey Name>

<One paragraph overview.>

**Time to complete:** <estimated time>
**Prerequisites:**
- <Required state or permissions>

---

## Step 1: <Action description>

<What the user does and why.>

![Step 1: <alt text>](<path-to-annotated-screenshot>)

1. **<Element name>** -- <What to click/fill/select and why>

---

## Step N: <Final step>

<Success confirmation: what the user sees when the journey is complete.>

![Step N: <alt text>](<path-to-annotated-screenshot>)

---

## Troubleshooting

### <Issue description>
**What you see:** <error message or unexpected state>
**Solution:** <how to fix it and continue the journey>
```

**Writing guidelines:**

1. **Action verbs for step titles:** "Navigate to the Projects page", not "The Projects Page".
2. **One action per step.** Do not combine multiple interactions.
3. **Be specific about what to click.** Bold the exact button/link text.
4. **Describe what happens next** after each action.
5. **Reference callouts by number:** "Click the button marked **(1)**."
6. **Decision points as conditional blocks:**

```markdown
## Step 3: Choose your project type

- **If creating a web application:** Click **"Web App" (1)** and proceed to [Step 4](#step-4).
- **If creating an API:** Click **"API" (2)** and skip to [Step 5](#step-5).
```

7. **Mark optional steps** with "(Optional)" prefix.
8. **Form field guidance:** List each field with expected value, format, and validation rules.

For short branches (1-2 steps), include all paths inline. For long branches (3+ steps), split into separate sub-sections or articles with cross-references.

**Troubleshooting section:** Pull from `error_patterns` for errors related to routes in the journey. Document common failure points (validation errors, permission denials) and the recovery path.

### Step 8: Order and Group Journey Articles

**Priority order for sidebar arrangement:**

| Priority | Journey Type |
|----------|-------------|
| 1 | Onboarding / Getting Started |
| 2 | Authentication |
| 3 | Core workflow (primary value action) |
| 4 | Secondary workflows |
| 5 | Settings and configuration |
| 6 | Billing and account management |
| 7 | Admin and advanced |

Use a `guides/` slug prefix and order numbers 100-899 (route-level docs use 1-99):
- 100-199: Onboarding. 200-299: Auth. 300-499: Core workflows. 500-599: Secondary. 600-699: Settings. 700-799: Billing. 800-899: Admin.

### Step 9: Integrate with Existing Doc Site

**Load existing manifest:**
```
Call mcp__kodadocs__load_manifest with:
  project_path: "<project-root>"
```

**Create article objects:**
```json
[
  {
    "title": "How to Sign Up and Set Up Your Account",
    "slug": "guides/getting-started",
    "content": "<journey article markdown>",
    "order": 100
  }
]
```

**Assemble the site:**
```
Call mcp__kodadocs__assemble_vitepress with:
  articles: [<existing route articles> + <new journey articles>]
  screenshots_dir: "<screenshots directory>"
  brand_color: "<from manifest>"
  logo_path: "<from manifest or null>"
  output_dir: "<from manifest>"
  project_name: "<from manifest>"
  product_summary: "<from manifest>"
  discovered_routes: [<all discovered routes>]
```

**Save manifest with journey metadata:**
```
Call mcp__kodadocs__save_manifest with:
  project_path: "<project-root>"
  manifest: {
    <existing fields>,
    "user_journeys": {
      "generated_at": "<ISO timestamp>",
      "journey_count": <number>,
      "journeys": [
        { "name": "...", "type": "...", "routes": [...], "article_slug": "guides/...", "step_count": N }
      ],
      "custom_journeys": <count>,
      "auto_detected_journeys": <count>
    }
  }
```

**Generate a journey index page** (order: 99) listing all guides in a table with columns: Guide, Description, Steps, Time. Group by journey type.

## Decision Trees

### App Type Classification

```
Does the route list contain "/products", "/catalog", "/cart", or "/checkout"?
  YES -> E-commerce application
Does it contain "/api-keys", "/docs", "/reference", "/sdk", or "/webhooks"?
  YES -> Developer tool
Does it contain "/dashboard", "/projects", "/team", or "/billing"?
  YES -> SaaS application
Does it contain "/admin", "/users", "/roles", or "/permissions"?
  YES -> Admin panel
Does it contain "/posts", "/articles", "/blog", or "/editor"?
  YES -> Content management system
None of the above?
  -> Generic web application (use universal patterns only)
If multiple match -> classify as the category with the most signals;
  apply patterns from all matching categories
```

### Journey Detection Confidence

```
HIGH (auto-generate):
  - Linear sequence, all routes connected in graph
  - Matches a known pattern, 3-8 steps

MEDIUM (confirm with user):
  - Some missing graph links, partial pattern match
  - 2 steps or 9-12 steps
  - Some routes inferred from code (not DOM)

LOW (suggest modifications):
  - Routes not connected in graph, no pattern match
  - 12+ steps (suggest splitting)
  - Routes span different functional areas
```

### Route-to-Journey Assignment

```
Can a route appear in multiple journeys?
  YES -> /dashboard can be the end of onboarding AND start of project creation.

Must all routes be in a journey?
  NO  -> Standalone routes (/privacy-policy, /terms) stay in route-level docs.

Route only reachable via a journey (/onboarding/step-2)?
  -> Document only within journey context, skip separate route-level article.
```

### Auth-Gated Routes

```
Journey crosses an authentication boundary?
  YES -> Auth config available?
           YES -> Capture in authenticated state, document login with placeholders
           NO  -> Warn, offer placeholder screenshots for authenticated pages
  NO  -> Proceed normally

Journey requires specific roles?
  YES -> Note in Prerequisites. If role cannot be simulated, note screenshots
         may differ by role.
```

### Large Application Scaling

```
1-15 routes -> Detect all journeys (likely 2-5)
16-40 routes -> Detect and group (likely 5-12)
41-100 routes -> Limit to top 15 by confidence; ask user for more
100+ routes -> Limit to top 10; suggest custom journey definitions
```

## Output Format

The skill produces:

1. **Navigation graph** -- Directed graph of transitions (internal use)
2. **Journey definitions** -- Structured list with routes, steps, types, confidence
3. **Step-specific annotated screenshots** -- Per-step callouts on relevant UI elements
4. **Journey articles** -- "How to" markdown with numbered steps, screenshots, decision points
5. **Journey index page** -- Landing page listing all guides
6. **Doc site integration** (optional) -- Articles added under "Guides" section
7. **Updated manifest** -- Journey metadata saved to pipeline state
8. **Console summary:**

```
User journey documentation generated:
  Routes analyzed: 24
  Navigation links mapped: 67
  App type: SaaS application

  Journeys detected: 7
    - Onboarding (4 steps) [HIGH]
    - Project creation (5 steps) [HIGH]
    - Team invitation (3 steps) [HIGH]
    - Settings management (4 steps) [MEDIUM]
    - Billing upgrade (4 steps) [MEDIUM]
    - Password reset (3 steps) [HIGH]
    - Admin user management (5 steps) [MEDIUM]
  Custom journeys added: 1
    - Data export (3 steps)

  Total articles: 8 | Total step screenshots: 31
  Saved to: guides/*.md
```

## Error Handling

### No navigation links found in DOM
Fall back to source code analysis for navigation patterns. If that also yields nothing, inform the user and offer to accept manually defined journeys.

### Application requires authentication but no auth config provided
Capture public routes only. Warn that most routes require auth. Generate journeys for public flows only (login, signup, password reset). Offer to retry with auth config.

### Circular navigation detected
Normal and expected (back-nav, breadcrumbs). Follow cycles only once when building journeys. Terminate when a previously visited route is encountered.

### Route returns an error page
Exclude that step. If mid-journey, split into two sub-journeys. If only 1 step remains, discard the journey. Warn with the route path and journey name.

### Too many journeys detected (20+)
Rank by confidence. Present top 10 to the user. Do not generate all without confirmation.

### Duplicate or overlapping journeys
If two journeys share 70%+ of routes in sequence, flag as duplicates. Ask user to merge or keep separate. If merging, combine unique steps under the longer name.

### Screenshot annotation fails
Use the unannotated screenshot. Replace callout references with descriptive location text ("Click the button in the top-right corner" instead of "Click (1)").

### Custom journey references nonexistent routes
Warn with the invalid route. Suggest the closest match by string similarity. Do not include nonexistent routes.

### Journey step has no screenshot
Include the step without a screenshot. Add a note: "[No screenshot available. The page requires specific conditions to display.]"

## Success Criteria

The run is successful when:
- [ ] All routes were discovered and screenshots captured for accessible routes
- [ ] A navigation graph was built from DOM links and source code analysis
- [ ] The application was classified by type (SaaS, e-commerce, developer tool, etc.)
- [ ] Journey patterns were detected using graph analysis and app type heuristics
- [ ] Detected journeys were presented to the user for review
- [ ] Custom journeys were validated against discovered routes
- [ ] Per-step annotated screenshots were generated with targeted callouts
- [ ] Each journey article follows the "How to" template with numbered steps
- [ ] Decision points are documented with conditional branching
- [ ] Each article includes a troubleshooting section
- [ ] Articles are ordered by priority (onboarding first, admin last)
- [ ] A journey index page lists all guides
- [ ] Articles were integrated into the VitePress site (if manifest exists)
- [ ] The manifest was updated with journey metadata
- [ ] Console summary was printed with statistics and confidence scores
