User Journey Map

---
name: user-journey-map
description: Map a customer's end-to-end journey toward an outcome — 3–6 stages, each with actions, emotions, pains, and opportunities, plus a rendered Mermaid emotion arc and the ranked pain points design should attack first. Use when the user wants a journey map, customer experience map, "map the user's path through onboarding", touchpoint analysis, or "where do users feel friction".
---

# user-journey-map

Maps what one customer experiences on the way to one outcome — outside-in, frontstage only — and converts the map's pains into a **ranked improvement target**, because a journey map that ends as wall art has failed. The emotional low points get found and named (peak-end rule: users judge an experience by its worst moment and its ending, not its average), so downstream design knows exactly which two stages to fix first. Sibling of `architecture-diagrams` (systems, not people) and upstream of `prd-draft` / `user-story-splitter` when an opportunity becomes committed work.

## How to respond

**Four rules come before the steps and outrank them:**

- **Answer what was asked, first.** Open with the answer, the decision or the artifact, in plain words. Scores, matrices, frameworks and tags come after it, and anything that doesn't change the answer is cut.
- **Use only what you were given.** Don't add facts, names, numbers, incidents, history, steps or sections the input doesn't contain. What you need and don't have is left out of the artifact and listed once at the end under "To confirm".
- **Deliver from what you have.** When the request gives you something to work on, state your assumptions in a line and produce the result. When it gives you nothing to work on, ask for it in one or two plain sentences and say what you will do once you have it.
- **Write for someone who has never heard of this skill.** No skill names, no paths or scripts from this folder, no internal terms, and nothing about how the run was set up. A next step is one plain sentence at the end that describes the work.
- **For this skill:** Call the map a hypothesis when it isn't built on research. Scores on the emotion arc show its shape; say once that they are estimates, and build the persona only from what the user told you.

1. **Anchor persona, outcome, and evidence level.** Ask at most 2 questions, spent on the weakest anchors: *"whose journey — one specific persona?"* and *"what outcome are they trying to reach?"* No persona or outcome → don't draft; a journey for "users" toward "using the product" has no stage boundaries. Non-interactive run (no user to ask): derive a specific persona and outcome from the input if defensible and tag them `[assumption]`; underivable → emit `BLOCKED: need persona + outcome` naming both. Tag the whole map's **evidence level**: `[observational]` (interviews, session recordings), `[survey/analytics]`, or `[assumption-based]` (team hypothesis). Assumption-based is legitimate — it's a hypothesis that directs research — but it must say so at the top, not masquerade as findings.

2. **Fix the journey's edges.** Start trigger (the event that puts the persona on this path — in their life, not on your site: ✅ *"payroll fails on the last Friday of the month"*) and end state (what "done" means *to the persona* — ❌ "completes checkout" if their outcome is "salary problem solved"). Wrong edges are the most common defect: starting at the landing page amputates the discovery pain, ending at purchase hides the abandonment cliff in activation.

3. **Divide into 3–6 named stages.** Stages are coarse phases of the persona's goal — *discover, evaluate, start, get value, return* — never screens or clicks. More than 6 stages means the altitude has dropped to flow level; that's `user-story-splitter` / flow-design territory, say so and re-chunk.

4. **Fill the four rows per stage** — this table is the artifact's core:
   - **Actions**: what the persona does, in their words, frontstage only. What the org does backstage ("support reviews the request") is out of scope — note it in the hand-off, don't map it.
   - **Emotion**: score 1–5 with the *reason*: ✅ *"2 — asked for the same information a third time"* — ❌ *"2 — frustrated"*.
   - **Pains**: friction, confusion, dead ends — each tagged with the step-1 evidence level if it differs from the map's default.
   - **Opportunities**: what would change the experience if the pain were removed — stated as an outcome, not a solution: ✅ *"never re-enter data the system already has"* — ❌ *"add autofill"* (that's a design decision that belongs downstream).

5. **Mark the peaks, then rank.** From the emotion row: the **1–2 steepest dips** and the **single highest peak**, plus the *ending* emotion (peak-end rule counts it double). Rank the opportunities: severity of the dip × how many personas/journeys hit it × evidence strength. Top 2 opportunities become the named improvement targets; the rest are listed but explicitly deprioritized — an unranked list re-delegates the judgment to the reader.

6. **Render and emit** with [`templates/journey-map.md`](templates/journey-map.md), in one message: the stage table, a Mermaid `journey` diagram (one `section` per stage, scored actions drawing the emotion arc), ranked opportunities with the two named targets, and hand-offs — target becomes committed work → `prd-draft` or `user-story-splitter`; measurement for a fix → `success-metrics`; backstage causes implicated → name them for the service owner. See [`examples/b2b-saas-onboarding.md`](examples/b2b-saas-onboarding.md) for the full pattern.

## Useful references in this skill

- [`templates/journey-map.md`](templates/journey-map.md) — stage table, Mermaid journey skeleton, ranked-opportunities block
- [`examples/b2b-saas-onboarding.md`](examples/b2b-saas-onboarding.md) — worked example: trial-to-activation journey, assumption-based, with ranked targets

## Quality bar

- **One persona, one outcome**, both named in the title. A map for "users" is a map of nothing.
- **The evidence level is declared at the top** and every pain that deviates from it is tagged individually.
- **Stage edges live in the persona's life**, not on the product's surface — the trigger precedes the product; the end state is the persona's outcome.
- **Every emotion score carries its reason.** A bare number row is decoration.
- **Opportunities are outcomes, not features.** The moment "add a button" appears, the map has started doing design's job without design's process.
- **The dips, the peak, and the ending are explicitly marked**, and exactly 1–2 opportunities are named as the targets. Ranking is the deliverable.
- **The Mermaid renders.** Scores 1–5, one section per stage — check syntax before emitting.

## When to use this skill

- ✅ "Map the customer journey through onboarding/purchase/support"
- ✅ "Where do users feel the most friction?" — with or without research data
- ✅ Before a redesign: agree on the as-is experience and where it hurts most
- ✅ Turning scattered user feedback into one shared picture of the path

## When NOT to use this skill

- ❌ Screen-by-screen interaction or flow design — that's below this altitude; the map hands off to it
- ❌ Internal/employee process mapping — this skill is outside-in; org-internal flows are a process diagram (`architecture-diagrams` sequence flows)
- ❌ Backstage service wiring behind the touchpoints — `reverse-architecture` / `architecture-diagrams`
- ❌ A committed feature needing requirements — `prd-draft`

## Anti-patterns to avoid

- ❌ **One stage per screen.** "Landing → Signup form → Email verify → Dashboard" is a screen list, not a journey — stages are phases of the persona's goal.
- ❌ **Mapping the org, not the customer.** "Support triages the ticket" is backstage; the customer's row says *"waits two days, chases twice"*.
- ❌ **Hypothesis dressed as research.** An assumption-based map presented without its tag poisons every decision built on it. The tag is load-bearing.
- ❌ **Happy-path-only journeys.** A map with no dip below 3 didn't look — errors, waits, and re-entry live in every real journey.
- ❌ **Solutioning in the opportunities row.** "Add SSO" pre-empts design with a guess; "signing in stops being the reason trials stall" keeps the problem open and measurable.
- ❌ **The unranked pain inventory.** Fourteen equal pains means the reader does the prioritizing — the map's whole job was to do it for them.
- ❌ **Showing the machinery.** The reply and the artifact are for the person who asked. Don't mention this skill, its files, templates, caps or internal terms, or that the run is non-interactive. Name another skill once, at the end, as a suggested next step, never inside the artifact.