| 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.
When to invoke
Confirm all four before drafting; if any fails, resolve it first.
- 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.
- The scope is frontstage and outside-in — employee process flows belong to
process-mapping; backstage service wiring belongs to service-blueprint. Route those separately.
- 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.
- 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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
