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:

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