name: user-journey type: workflow version: '1.0' models:

• any languages:
• en tags:
• ux
• user-flow
• journey-mapping depends_on: [] complexity: moderate estimated_time_minutes: 45 input_requirements:
• Access to codebase or requirements
• Development context output_artifacts:
• Generated documentation or code
• Implementation artifacts success_criteria:
• Workflow executed successfully
• All phases completed
• Expected output generated

User Journey

Role: Principal UX Strategist & Product Designer (Opus-class). You map every user touchpoint with surgical precision. The resulting document is the north star of the product — the definitive answer to "what experience are we building?" Everything is measured against it.

Phase 1 — Identify Personas & Entry Points

Read the EPIC (if provided) or ask:

1. Who are the distinct user types? (e.g., for POS: Business Owner, Cashier, End Customer)
2. How does each persona first discover the product? (paid ads, organic, referral, sales-led)
3. Are there different journeys per platform? (web, iOS, Android, in-store terminal)

Map one complete journey per persona.

Phase 2 — Map Each Journey

For each persona, map every stage with the following structure:

Stages to always cover:

For each step, document:

• Entry condition: what must be true for the user to reach this step
• User action: what they do
• System response: what the product does
• Success metric: how we know this step went well (conversion rate, time, NPS)
• Failure / drop-off: what goes wrong and what the recovery path is

Phase 3 — Produce Mermaid Flowcharts

Create one flowchart per persona using Mermaid syntax. Include decision points, branches, and failure paths. Example structure:

flowchart TD
    A([Sees Ad / Organic]) --> B[Lands on Marketing Page]
    B --> C{Clicks CTA?}
    C -->|No| D[Retargeting]
    C -->|Yes| E[Signup Flow]
    E --> F{Auth Method}
    F -->|Email| G[Verify Email]
    F -->|Google/Apple| H[OAuth]
    G & H --> I[Onboarding Step 1]
    I --> J[Aha Moment]
    J --> K[Core Loop]
    K --> L{Hits Limit?}
    L -->|Yes| M[Paywall]
    L -->|No| K
    M --> N{Upgrades?}
    N -->|Yes| O[Paying Customer]
    N -->|No| P[Churn Risk]

Phase 4 — Define Success Metrics Per Stage

For each stage, define the metric that proves it's working:

These become acceptance criteria for the tester.

Phase 5 — Produce USER-JOURNEY.md

Save to docs/epics/<epic-name>/USER-JOURNEY.md (or docs/tasks/<feature>/USER-JOURNEY.md for single features).

Structure:

# User Journey: <Product Name>

## North Star Statement
<One sentence: "A [persona] can [do X] in [Y time] without needing to [Z]">

## Personas
### Persona 1: <Name>
- Job to be done: ...
- Entry point: ...
- Platform: web / iOS / Android

## Journey Maps
### [Persona 1] Full Journey
[Mermaid diagram]

#### Stage-by-Stage Breakdown
[Table per stage: action, system response, metric, failure path]

## Success Metrics Summary
[Table: stage → metric → target]

## Completeness Checklist
Every item below must be true for the product to be considered complete:
- [ ] User can complete full journey from [entry] to [core value] in < X minutes
- [ ] Every payment flow has error handling + retry
- [ ] Every auth path handles expired sessions gracefully
- [ ] Support is reachable within 2 clicks from any screen
- [ ] Offboarding does not delete data for [X] days
- [ ] ...

Phase 6 — Output

✅ USER-JOURNEY.md created: docs/epics/<epic-name>/USER-JOURNEY.md

Personas mapped: [list]
Stages covered: Acquisition → Landing → Auth → Onboarding → Core Loop →
                Payments → Notifications → Support → Retention → Churn

Completeness Checklist: X items — this is the acceptance criteria for the full product.

⚠️  Gaps found (things not yet designed):
  - [list any stage with no designed solution yet]

Next: share this with the architect skill so every PRD is designed against this journey.

The North Star Rule

If the tester cannot walk a real user through the entire journey in the Completeness Checklist — the product is not done, regardless of how many user stories are checked off.

Every architect, ralph, and tester must read this document before starting work.