journey-mapping git:20260727.7ba66d5A

Immutable. This exact content is served forever at /api/v1/blob/53d0d394d51e1735.

---
name: journey-mapping
description: Use when a product team needs to understand how a customer moves through an experience end-to-end — mapping the stages, actions, emotions, pains, and opportunities along the path. Triggers on "map the customer journey", "what does the user go through", "journey map this flow", "map out the experience stages", "what are the customer touchpoints", "where does the user feel pain". Carries a platform/surface axis (responsive-web, iOS, Android, cross-platform) that changes what the method asks at each stage. Scoped to customer/end-user journeys only — employee journeys are out of v1. Do NOT use to design screen interactions (use `user-flow`), to blueprint the backing services (use `service-blueprint`), or to map an internal business process (use `process-mapping`).
---

# Skill: journey-mapping

Produces a **customer/end-user journey map** — the stages a customer moves through, the actions they take, the emotions they feel, the pains they encounter, and the opportunities those pains reveal. The map is **outside-in and frontstage**: it describes what the customer experiences, not what happens behind the scenes. The method draws on NN/g journey mapping, Patton user-story mapping, and Torres opportunity-solution tree thinking; see `references/journey-mapping.md`.

**Inputs:** a persona (or role description) and an outcome the customer is trying to achieve. Both are elicited inline when absent — this skill is standalone-useful without upstream research artifacts. **Consumed by:** `user-flow` (derives the screen sequence and per-screen briefs from the journey stages) and `service-blueprint` (maps the frontstage actions to backstage services). When `architect` or `contracts` are not installed, downstream services are named textually rather than by package reference.

## Output rendering

Table — When presenting several items that share the same fields, render a Markdown table. Cap at ~5 columns; beyond that, switch to a per-item detail list. Right-align numeric columns.

## When to invoke

Confirm all four before drafting; if any fails, resolve it first.

1. **There is a customer goal to map** — name the outcome the customer is trying to achieve. If the team has no sense of who the customer is or what they want, elicit persona + outcome inline before proceeding.
2. **The scope is frontstage and outside-in** — employee process flows belong to `process-mapping`; backstage service wiring belongs to `service-blueprint`. Route those separately.
3. **You know the surface** — confirm `surface` before drafting: `responsive-web | iOS | Android | cross-platform`. Surface changes what the method asks at key stages; see step 1 below.
4. **No current journey map exists for this outcome and surface** — if one exists, you are amending it, not starting fresh. Check for an existing artifact at the path resolved in step 4.

## Procedure

1. **Set the surface and genre.** Confirm the target surface (`responsive-web | iOS | Android | cross-platform`). Note the platform-specific conventions the journey must honor — context-switching patterns on iOS, navigation conventions on Android, progressive-disclosure on responsive web, shared-intent-then-adapt on cross-platform. Consult `references/journey-mapping.md` § Platform/surface axis. Point to the relevant platform conventions; do not reprint their values. Also confirm the **surface genre** from the per-screen brief's `surface-genre:` field, or elicit: "What kind of surface is this?" Genre shapes the canonical stage vocabulary — consult `references/surface-genre-journeys.md` for the 7 genre stage scaffolds.
2. **Elicit or confirm the persona, outcome, and evidence level.** If no persona artifact is present, ask: who is the customer, and what outcome are they trying to reach? Name a role and an outcome; you need both to anchor the stage boundaries and the emotion baseline. Also declare the **evidence level** of the source material: `observational` (direct research — user interviews, usability sessions, diary studies), `survey-backed` (quantitative signals — analytics, surveys, NPS), or `assumption-based` (team hypotheses, no primary research yet). Record as `evidence-level: <level>` in the journey map's frontmatter. An assumption-based map is a hypothesis, not a defect — it is valuable when it drives future research decisions; label it clearly. Load `references/journey-mapping.md` § Grounding the map. When you are eliciting this *with* stakeholders rather than from an existing artifact, run it as a **facilitated workshop** — anchor on a single persona, generate silently before discussing, and keep the room small; see `references/facilitation.md`.
3. **Scope the journey.** Name the start trigger (what initiates the journey) and the end state (what done looks like for the customer). Agree these before dividing the middle — wrong boundaries produce stages that don't serve the team's questions.
4. **Divide into stages.** Break the journey into three to six named stages (more implies finer work than a journey map is the right tool for — reach for Patton's user-story mapping for that). Each stage is a coarse phase of the customer's goal, not a screen or a step. Load `references/journey-mapping.md` § Stage construction.
5. **Populate each stage.** For each stage, capture four rows: **Actions** (what the customer does — frontstage only, in the customer's words), **Emotions** (how they feel — emotional arc across the journey, the key design input), **Pains** (friction, confusion, or gaps the customer encounters), **Opportunities** (what would change the experience if addressed). The pains-to-opportunities column is the primary output — it is where journey maps earn their keep. Load `references/journey-mapping.md` § The four rows. Also record each distinct frontstage action as a `- **Action:** <action-slug>` marker in the template's `## Frontstage actions` block — the structural-orphan lint reads each `**Action:**` line as an `action` chain node, and `user-flow` ties each screen action to one.
6. **Identify peak moments.** From the emotion arc in step 5, identify the **1–3 stages with the steepest negative dip** (the lowest-emotion moments) and the **single most-positive peak** (the highest-emotion moment). Mark these explicitly in the map. Downstream design is weighted toward improving the negative peaks first — this is the Kahneman peak-end rule applied to experience design: the overall judgment of an experience is disproportionately shaped by its most intense moment (positive or negative) and its end, not its average. A journey with an obvious peak moment and a named low point gives `design-principles` and `user-flow` a ranked improvement target, not an undifferentiated list of pains.
7. **Resolve the path and surface it.** Resolve `<output_dir>` following the config-driven, two-branch elicitation procedure in `references/agentbundle-layout.md`. Resolution order: (1) repo-root `./agentbundle-layout.toml` `[design] output_dir` — repo-scope takes priority; (2) user-profile `~/.agentbundle/agentbundle-layout.toml` `[design] output_dir`; when neither resolves, two-branch elicitation runs — never a silent default: **(a) Repo branch** — suggest `docs/design/` and offer to write `output_dir` to `./agentbundle-layout.toml [design]`; **(b) Personal/vault branch** — ask for an absolute path (e.g. `~/Documents/<VaultName>/design/`) and write to `~/.agentbundle/agentbundle-layout.toml [design]`. Expand to a full absolute path (`~`-expand, realpath-resolve, reject `..` escapes); a repo-root-sourced `output_dir` that resolves outside the repo tree is untrusted-origin — confirm before writing. **Surface the resolved path to the adopter before writing.** Write to `<output_dir>/journeys/<slug>.md`; create `journeys/` lazily on first write. Add frontmatter `type: customer-journey` and `evidence-level: <level>` to the output file.
8. **Check against the quality floor.** Verify the map does not hardwire a surface-specific interaction idiom into a stage — the platform axis changes the *questions*, not the output values. Confirm no reprinted breakpoints, HIG spacings, or Material values appear in the artifact.
9. **Hand off.** Surface which stages carry the highest-opportunity pains and which stage is the peak negative moment (the input `user-flow` needs to sequence screens around these). Name any backstage services implied by the actions (the input `service-blueprint` will expand). Point the user to `user-flow` for the next step, or to `service-blueprint` if the service architecture question is more pressing.

## Anti-patterns to refuse

- **Mapping employee-side steps as customer stages.** A journey map is outside-in and frontstage. What happens inside the organisation or system is `process-mapping`'s domain; what the customer sees and does at each stage is this skill's. If a stage is "the support team reviews the request," it belongs behind the line of visibility — in `service-blueprint`, not here.
- **Reprinting platform values.** The platform/surface axis changes what the journey questions are; it does not print HIG spacing, Material breakpoints, or responsive pixel values into the map. Point to the platform conventions; let the method derive how they shape the stages.
- **One stage per screen.** Stages are coarse phases — "discover," "onboard," "get value," "return." Screens come later, in `user-flow`. A journey that has one stage per screen is not a journey map; it is a screen list that hasn't been sequenced yet.
- **Treating pains as blockers, not as input.** A pain on a journey map is an opportunity waiting to be framed — it is the primary reason the map exists. Don't resolve pains into design decisions here; hand them to `user-flow` and Torres opportunity-solution thinking.
- **Starting without a persona and outcome.** A journey with no named customer and no stated outcome has no anchor for stage boundaries or emotion baseline. Elicit both before the first stage boundary lands.