journey-mapping git:20260810.be07f23A

Immutable. This exact content is served forever at /api/v1/blob/0177ba275950f2fc.

---
name: journey-mapping
description: "Use when a team asks what an end user goes through across an experience, from one meaningful outcome to the next. Produces a customer journey map of stages, actions, touchpoints, emotions, pains, and opportunities, adjusted for the relevant platform. Use `service-blueprint` for backing services, `user-flow` to turn the journey into screens, and `process-mapping` for internal operations. Adoption strategy belongs to product strategy; selecting and scoping a bet belongs to product-engineering shaping; implementing journey screens belongs to `frontend-engineering`."
---

# 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.