---
name: User Journey Mapping
slug: user-journey-mapping
category: AI Engineering
description: User Journey Mapping turns personas, features, and KPIs into step-by-step user paths from trigger to value moment. Use it when defining user journeys, user flows, or the pain-to-value sequence for a PRD.
github: "https://github.com/mattgierhart/PRD-driven-context-engineering/tree/main/.claude/skills/prd-v04-user-journey-mapping"
language: HTML
stars: 182
forks: 10
install: "npx degit https://github.com/mattgierhart/PRD-driven-context-engineering/tree/main/.claude/skills/prd-v04-user-journey-mapping ~/.claude/skills/prd-v04-user-journey-mapping"
installs_to: ~/.claude/skills/prd-v04-user-journey-mapping
source_path: .claude/skills/prd-v04-user-journey-mapping/SKILL.md
collection_size: 25
category_size: 3475
collection_url: "https://dirskills.com/collections/mattgierhart/PRD-driven-context-engineering"
added: 2026-09-07T05:20:14.007Z
last_synced: 2026-09-07T05:20:14.007Z
canonical_url: "https://dirskills.com/skills/user-journey-mapping"
---

# User Journey Mapping

User Journey Mapping turns personas, features, and KPIs into step-by-step user paths from trigger to value moment. Use it when defining user journeys, user flows, or the pain-to-value sequence for a PRD.

**Install:**

```bash
npx degit https://github.com/mattgierhart/PRD-driven-context-engineering/tree/main/.claude/skills/prd-v04-user-journey-mapping ~/.claude/skills/prd-v04-user-journey-mapping
```

## README

# User Journey Mapping

Position in workflow: v0.4 Persona Definition → **v0.4 User Journey Mapping** → v0.4 Screen Flow Definition

User journeys transform features into paths. A journey answers: "How does [persona] go from [trigger] to [value moment] using [features]?"

## Consumes

This skill requires prior work from v0.3-v0.4:

- **PER-\* persona entries** (from v0.4 Persona Definition) — Behavioral profiles that journeys are built around; each journey belongs to a specific persona
- **FEA-\* feature entries** (from v0.3 Features Value Planning) — Feature list that becomes journey steps; validates that journeys use only MVP-scoped features
- **KPI-\* outcome definitions** (from v0.3 Outcome Definition) — Success metrics that journeys drive; Core journeys must tie to Tier 1/2 KPIs
- **MVP-SCOPE artifact** (from v0.3 Features Value Planning) — Explicit feature boundary; journeys must use only features in MVP-SCOPE, no backlog features
- **BR-\* business rules** (from v0.3 Commercial Model) — Constraints that affect journey design (pricing tiers affect onboarding paths, moat rules affect targeting journeys, etc.)

This skill assumes v0.4 Persona Definition is complete.

## Produces

This skill creates/updates:

- **UJ-\* entries** (user journeys, confidence 2-3/5) — Paths from trigger through steps to value moment, tied to PER-/FEA-/KPI- with pain point identification
- **Journey sequencing artifact** — Dependency map showing which journeys gate which (Onboarding gates Core; Core gates Power User)

All UJ- entries should include:
- `confidence: 2-3/5` (based on design validation and feature implementation certainty)
- Evidence source citations (PER-ID, FEA-ID, KPI-ID references)
- Forward target: "Would move to 4/5 if validated in beta with actual persona users"

Example UJ- entry with confidence:
```markdown
UJ-001: First Report Generation
Persona: PER-001 (Overwhelmed Ops Manager)
Type: Core
Trigger: User completes onboarding and sees empty dashboard
Goal: Generate first automated report to see time-saving value
Confidence: 2/5 (source: design-validation + feature-status-in-development; KPI-002 links to conversion)

Steps:
  1. Click "Create Report" → FEA-003 (one-click reports) [In MVP-SCOPE]
  2. Select data source → FEA-001 (auto-sync) [In MVP-SCOPE]
  3. Choose report template → FEA-008 (templates) [In MVP-SCOPE]
  4. Preview report → FEA-003 [In MVP-SCOPE]
  5. Export/share report → FEA-009 (export) [In MVP-SCOPE]

Pain Points:
  - Step 2: User may not have connected data source yet (dependency on UJ-002)
  - Step 3: Template overload if too many choices (design concern; recommend 3-5 templates max)

Moment of Value: Seeing the completed report with their actual data
KPI Link: KPI-002 (activation rate — user completes first valuable action)
Success Metric: Time from "Create Report" click to export ≤ 5 minutes
Dependencies: BR-015 (data format rules), UJ-002 (data source connection must precede)

Next Target: "Would move to 4/5 if 5+ beta users complete this journey in ≤5 minutes and report value"
```

## Journey Types

| Type | Purpose | Priority Signal | Example |
|------|---------|-----------------|---------|
| **Core** | Primary value delivery | Must complete for activation | First report generated |
| **Onboarding** | First-time user setup | Blocks all other journeys | Account creation → first action |
| **Recovery** | Error handling, support | Retention protection | Password reset, billing issue |
| **Power User** | Advanced workflows | Expansion/upsell | Bulk operations, integrations |

**Rule**: Define Onboarding first (it gates everything), then Core journeys (they deliver KPI-), then others.

## Journey Anatomy

Every journey has:

1. **Trigger** — What causes the user to start? (Event, not "opens app")
2. **Steps** — Actions linked to FEA- features
3. **Pain Points** — Where friction exists (design around these)
4. **Moment of Value** — When user achieves goal (this drives KPI-)

## Mapping Process

1. **Pull PER-** (personas) from Persona Definition
   - Each journey belongs to a specific persona

2. **Pull FEA-** (features) and KPI- (outcomes) from v0.3
   - Features are the building blocks of journey steps
   - KPIs tell you which journeys matter most

3. **Define trigger events**
   - What causes the user to start this journey?
   - Be specific: "Receives calendar invite" not "opens app"

4. **Map step flow using features**
   - Each step = an action the user takes
   - Link each step to the FEA- that enables it

5. **Identify pain points**
   - Where might the user get confused, frustrated, or blocked?
   - These inform UX design decisions

6. **Mark "moments of value"**
   - When does the user get the payoff?
   - This should tie to KPI- measurement

7. **Create UJ- entries** with full traceability

## UJ- Output Template

```
UJ-XXX: [Journey Title]
Persona: [PER-XXX]
Type: [Core | Onboarding | Recovery | Power User]
Trigger: [Event that initiates journey]
Goal: [What user wants to accomplish]

Steps:
  1. [Action] → FEA-XXX
  2. [Action] → FEA-XXX
  3. [Action] → FEA-XXX
  ...

Pain Points:
  - [Step X]: [Potential friction — e.g., "requires context switch"]
  - [Step Y]: [Potential friction]

Moment of Value: [When user achieves goal — be specific]
KPI Link: [KPI-XXX this journey drives]
Success Metric: [How we measure journey completion]
Dependencies: [BR-XXX constraints, API-XXX if known]
```

**Example UJ- entry:**
```
UJ-001: First Report Generation
Persona: PER-001 (Overwhelmed Ops Manager)
Type: Core
Trigger: User completes onboarding and sees empty dashboard
Goal: Generate first automated report to see time-saving value

Steps:
  1. Click "Create Report" → FEA-003 (one-click reports)
  2. Select data source → FEA-001 (auto-sync)
  3. Choose report template → FEA-008 (templates)
  4. Preview report → FEA-003
  5. Export/share report → FEA-009 (export)

Pain Points:
  - Step 2: User may not have connected data source yet (dependency on UJ-002)
  - Step 3: Template overload if too many choices

Moment of Value: Seeing the completed report with their actual data
KPI Link: KPI-002 (activation rate)
Success Metric: Time from "Create Report" click to export ≤ 5 minutes
Dependencies: BR-015 (data format rules), UJ-002 (data source connection)
```

## Feature-to-Journey Validation

After mapping journeys, validate:

- [ ] **No orphaned features**: Every FEA- appears in at least one UJ-
- [ ] **No journey gaps**: Every step has a FEA- that enables it
- [ ] **KPI coverage**: Core journeys tie to Tier 1/2 KPIs

If a FEA- isn't in any journey, either:
1. Add it to a journey (you missed a use case), or
2. Cut it from scope (it's not needed)

## Journey Sequencing

Map dependencies between journeys:

```
UJ-000: Onboarding (gates all)
    ↓
UJ-001: First Report (Core) ← KPI-002 (activation)
    ↓
UJ-002: Data Source Connection (Core) ← KPI-003 (depth)
    ↓
UJ-003: Team Invite (Power User) ← KPI-004 (expansion)
```

## Anti-Patterns to Avoid

| Anti-Pattern | Signal | Fix |
|--------------|--------|-----|
| **Feature-first journeys** | Steps = feature list dumped in order | Start with user goal, then map features to it |
| **No trigger** | "User opens app" | Define specific event: "receives notification" |
| **No value moment** | Journey ends without payoff | Each journey needs clear outcome |
| **Orphaned features** | FEA- not in any journey | Add to journey or cut from scope |
| **Generic personas** | "User does X" | Specify PER-: "PER-001 does X" |
| **Happy path only** | No pain points identified | Anticipate where users struggle |
| **Mega-journeys** | 15+ steps | Split into sub-journeys |

## Quality Gates

Before proceeding to Screen Flow Definition:

- [ ] Onboarding journey defined first
- [ ] All Core journeys mapped to KPI-
- [ ] Every FEA- appears in at least one journey
- [ ] Every journey has a specific trigger (not "opens app")
- [ ] Pain points identified for friction design
- [ ] Journey dependencies documented

## Downstream Connections

UJ- entries feed into:

| Consumer | What It Uses | Example |
|----------|--------------|---------|
| **v0.4 Screen Flow Definition** | Steps become screens | UJ-001 Step 3 → SCR-005 |
| **v0.6 Technical Specification** | Journeys inform API sequences | UJ-001 → API-001, API-002 flow |
| **v0.7 Test Planning** | Journeys become E2E tests | TEST-020 validates UJ-001 |
| **v0.9 GTM** | Journey-based onboarding messaging | "Complete [UJ-001] in 5 minutes" |

## Detailed References

- **Journey mapping examples**: See `references/examples.md`
- **UJ- entry template**: See `assets/uj.md`
- **Journey sequencing guide**: See `references/sequencing.md`