---
name: customer_journey_mapping
description: Build evidence-based customer journey maps: one actor, one scenario, stages and touchpoints taken from research, emotions and pains tagged validated or hypothesis, root causes, and opportunities scored on severity, frequency, business impact, effort, and evidence strength. Triggers on "customer journey map", "journey mapping", "map the customer journey", "touchpoints and pain points", "moments of truth", "where do customers drop off", or a request to turn interviews, tickets, and funnel data into a prioritized journey roadmap.
---

# Customer Journey Mapping

## Purpose

Turn research into a journey map a team can act on. Most journey maps fail in one of two ways: they are a funnel template with emotions guessed in a workshop, or they are a wall poster with no scores, no owner, and no next step. This skill prevents both. Every cell on the map carries an evidence tag, every pain is written specific enough to score, and every opportunity leaves with a pain score, a priority score, a quadrant, and an owner.

A journey map here means: a visualization of the process one specific actor goes through to accomplish one specific goal with a product or service, built from research with real customers of that product. It is not an experience map (generic person, broad life context, no specific product) and not a service blueprint (which adds frontstage and backstage operations, systems, and handoffs). Build the journey map first. Blueprint only the worst stages, later, when the operational fix needs that detail.

Supporting files: `assets/journey-map-template.md` is the map itself, `references/evidence-and-scoring.md` holds the source hierarchy, scoring anchors, and anti-patterns, `references/worked-example.md` is a complete fictional map with verified scores, and `bin/score_opportunities.py` does the scoring math.

## Workflow

**1. Scope to one actor, one scenario, one decision.** Name the actor (a research-backed persona or segment), the scenario (the goal and its context, including the deadline or trigger), and the decision the map must inform. One point of view per map. If two actors take different paths, that is two maps. A map with no decision behind it is decoration, so stop and name the decision first.

**2. Inventory the evidence before mapping anything.** Gather what exists: customer interviews built around the actual sequence of events, funnel and drop-off analytics, support tickets and chat logs coded by reason, reviews and verbatims, frontline staff interviews, observation or usability sessions, per-touchpoint CSAT, CES, or NPS where available. Fill the evidence inventory in the template: source, type, date, stages covered, sample, limits. A map built from opinion alone is a hypothesis map. It can be drafted, but it must be labelled that way on its face and its first roadmap item is the research that would validate it.

**3. Derive the stages from the research, not from a template.** Stages are the phases customers actually pass through, in their order, including loops back and exits. Awareness, consideration, purchase, onboarding, use, support, renewal is a scaffold to check against the data, not a list to copy. If a stage exists in no interview, ticket, or funnel step, cut it. Name stages with the customer's verb where you can.

**4. Fill the map row by row.** For each stage: customer goal, actions, touchpoints and channels, thoughts and questions, emotion, pain points, at least one verbatim with its source id, and one stage metric with its source. Emotion runs -2 to +2 and comes from coded verbatims, ratings, or observed behaviour, never from workshop mood. Pain points must be specific and observable: "buyers cannot find where to upload the second document" scores; "onboarding is confusing" does not. Tag every row V (validated), partial, or H (hypothesis) per the rules in `references/evidence-and-scoring.md`.

**5. Read the curve and name the moments of truth.** Plot the emotion row in order. Mark the lowest point, the highest point, and the ending. People judge an experience largely by its worst or most intense moment and by how it ends, so a top pain sitting at the trough or at the ending outranks an equal pain mid-journey. List the two to four moments of truth: the interactions where the customer decides to continue, buy, stay, or leave, each with its current performance and source.

**6. Find root causes for the top pains.** For each top pain, work across four lenses: people, process, policy, tech. Add the backstage facts only where they explain a pain (the handoff, the rule, the system limit). Quantify the cost where the data allows it: lost conversion at that step, repeat contacts, handle time, refunds. No invented numbers; if the cost is unknown, write unknown and name the query that would answer it.

**7. Score every opportunity.** Write each fix as its own CSV row and run the scorer:

```
python3 bin/score_opportunities.py opportunities.csv
python3 bin/score_opportunities.py opportunities.csv --json
```

CSV columns: opportunity, stage, severity, frequency, business_impact, effort, evidence (validated, partial, or hypothesis). Scores are 1-5 using the anchors in the reference file. Each person scores alone before any group discussion. Pain = severity + frequency + business impact (3-15). Priority = pain x evidence weight (1.0, 0.6, 0.3) / effort. Quadrants: quick win (pain 11 or more, effort 2 or less), strategic (pain 11 or more, effort 3 or more), fill in (pain under 11, effort 2 or less), defer or drop (pain under 11, effort 3 or more). The tool sorts and ranks; the team may override the order for a peak or ending pain, or for weak evidence, and the override and its reason go on the map.

**8. Ship the roadmap and set the review.** Roadmap in three bands: now (quick wins, named owner), next (strategic items, each with its validation step first when evidence is partial or hypothesis), later or dropped (with the score that put it there). Set the review date before you finish: quarterly for fast-changing digital journeys, within six months otherwise, and immediately after a pricing, policy, or channel change. List the stage metrics to re-check at that review.

## Output Contract

- One completed map per actor and scenario, using `assets/journey-map-template.md`, with: scope and decision, evidence inventory with sample and limits, stage map with evidence tags and verbatims, emotion curve with peak-end check, moments of truth, root causes, scored opportunities, roadmap, validation steps, and review date.
- The opportunities CSV plus the scorer output (table or JSON) that the roadmap is based on.
- A gaps list: every H-tagged cell that matters, the research that would validate it, and who owns getting it.
- No stage, emotion, pain, metric, or quote on the map without a source id or an H tag.

## Operating Rules

1. Evidence before workshop. Research is gathered and sorted by stage before any group mapping session, and the session starts by reviewing it. A blank-canvas workshop produces brainstorming, not diagnosis.
2. One actor per map. Splitting late is expensive; if the paths diverge in the data, split the map at step 3, not after scoring.
3. Unverifiable gets cut or tagged H. No invented metrics, quotes, drop-off rates, or emotion scores, ever. A quote on the map is a real quote from a named source in the inventory.
4. Specific pains only. If a pain cannot be observed, counted, or quoted, rewrite it until it can, or drop it to the gaps list.
5. Score alone first, discuss second. Independent scoring before discussion is what keeps the loudest voice in the room from setting every score.
6. The math ranks, people decide, reasons get written down. Overrides are allowed and expected at peaks and endings. Undocumented overrides are not.
7. Strategic work on weak evidence validates first. No build starts on a hypothesis-tagged pain without the named validation step done and the tag updated.
8. Current state before future state. Draw the future journey only for the top scored opportunities. A full future-state map drawn from an unevidenced current state is fiction in two tenses.
9. Keep the map alive or kill it. An unowned map with no review date gets archived, not framed. One to three active maps per product area is a sane load; add a new one only when the existing ones are driving work.