# User Journey > Maps all user flows for a product with extreme clarity — from first touch (marketing, acquisition) through auth, onboarding, core usage, payments, support, and churn. Produces a Mermaid flowchart diagram and a structured USER-JOURNEY.md document. This document becomes the 'north star': if any part of the system doesn't fulfill this journey, the product is incomplete. The tester validates against it, the architect designs for it, ralph implements it. Use when starting a new product, after a vision/epic is defined, or when the user says 'user flow', 'user journey', 'experience map', or 'how does the user...'. - Skill: `elihuvillaraus/user-journey` (Agent Skill) - Install (CLI): `npx skillmds@latest add elihuvillaraus/user-journey` - Raw SKILL.md: https://api.skillmd.com/api/skills/elihuvillaraus/user-journey/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Marketing & Growth - Author: elihuvillaraus (https://skillmd.com/u/elihuvillaraus) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/elihuvillaraus/user-journey --- # 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: | Stage | What happens | |-------|-------------| | **Acquisition** | How they find the product (ad, SEO, referral, sales call) | | **Landing** | First impression — what they see, what the CTA is | | **Signup / Auth** | Registration flow, social auth, invitations, SSO | | **Onboarding** | First-run experience, setup steps, aha moment | | **Core Loop** | The repeated action that delivers primary value | | **Payments** | Trial, paywall, checkout, invoicing, receipts | | **Collaboration** | Inviting team, roles, permissions (if applicable) | | **Notifications** | How the product reaches the user outside the app | | **Support** | How they get help when stuck | | **Retention** | What brings them back (loyalty, habits, reminders) | | **Upgrade / Upsell** | When and how they're prompted to pay more | | **Churn / Offboarding** | How they leave — and what happens to their data | 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: ```mermaid 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: | Stage | Metric | Target | |-------|--------|--------| | Landing | CTA click rate | >3% | | Signup | Completion rate | >70% | | Onboarding | Aha moment reached | >60% in first session | | Core loop | D7 retention | >40% | | Paywall | Trial-to-paid conversion | >25% | | ... | ... | ... | These become **acceptance criteria** for the tester. --- ## Phase 5 — Produce USER-JOURNEY.md Save to `docs/epics//USER-JOURNEY.md` (or `docs/tasks//USER-JOURNEY.md` for single features). Structure: ```markdown # User Journey: ## North Star Statement ## Personas ### Persona 1: - 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//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 @architect 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. **See also `journey-map`** — once this document exists and the EPIC has real PRD progress, that skill turns it into a visual game-map showing which stages are actually built, in progress, or (most usefully) designed here but not implemented by any PRD yet.