| name | user-journey-mapping |
| description | Journey map formats, edge case discovery, and KPI definition per flow step. Use when mapping user flows from a PRD, identifying where things can go wrong, or defining measurable success criteria per journey. |
User Journey Mapping
A journey map translates a PRD from "what we're building" into "how a user actually experiences it." It exposes assumptions about user behavior, surfaces edge cases before they become bugs, and defines measurable checkpoints. The Feature Spec and QA agents consume journey maps directly — weak maps produce weak specs.
When to Use This Skill
- Translating a PRD into detailed user flows before feature spec writing
- Identifying edge cases and error states systematically
- Defining KPIs per step in a flow (not just end-state conversion)
- Validating that a proposed UX handles all real user scenarios
- Reviewing an existing flow for coverage gaps
Core Concepts
1. Happy Path vs. Non-Happy Golden Path vs. Edge Cases
- Happy path: The ideal user does everything in the expected order, no errors, no hesitation
- Non-happy golden paths: The most common alternative flows — what real users actually do most of the time
- Edge cases: The less common but possible states that must be handled gracefully
Mapping only the happy path is the most common journey mapping failure. Non-happy golden paths are where most of the user experience lives.
2. Steps Have States
Every step in a flow has multiple states:
- Loading — what does the user see while waiting?
- Success — what does the user see on completion?
- Empty — what does the user see when there's no content?
- Error — what does the user see when something fails?
- Partial — what does the user see with incomplete data?
Every state must be defined, not just the success state.
3. Measurement Points
Define what's measured at each step. A journey without measurement points can't be evaluated after launch.
Journey Map Format
# Journey Map: [Journey Name]
**User type:** [Who is performing this journey]
**Entry point:** [What triggers this journey — where does the user come from?]
**Exit point:** [What does success look like at the end?]
**Preconditions:** [What must be true before this journey begins?]
---
## Happy Path
### Step 1: [Step Name]
- **User action:** [What the user does]
- **System response:** [What the system does in response]
- **User sees:** [What's displayed / what happens in the UI]
- **Measurement:** [Event / metric tracked at this step]
### Step 2: [Step Name]
[Same structure]
---
## Non-Happy Golden Paths
### Variant A: [Name — e.g., "User skips optional step"]
- **Trigger:** [What causes this variant]
- **Modified steps:** [Which steps differ from the happy path]
- **Expected behavior:** [How the system handles this variant]
---
## Edge Cases
| Edge Case | Trigger | Expected Behavior | Severity |
|-----------|---------|-------------------|----------|
| [Edge case 1] | [What causes it] | [How system responds] | Critical / Major / Minor |
| [Edge case 2] | [What causes it] | [How system responds] | Critical / Major / Minor |
---
## Error States
| Error | Trigger | User-Facing Message | Recovery Path |
|-------|---------|---------------------|---------------|
| [Error 1] | [What causes it] | [What user sees] | [How to recover] |
---
## KPIs Per Step
| Step | Metric | Baseline | Target |
|------|--------|---------|--------|
| [Step 1] | [Completion rate / time-on-step / error rate] | [Current] | [Goal] |
| [Step 2] | [Metric] | [Current] | [Goal] |
---
## Drop-off Hypotheses
[Where are users most likely to abandon this journey and why?]
Edge Case Discovery Process
Systematic Edge Case Categories
For each step in a journey, check each category:
Input Boundaries
- What happens with the minimum valid input?
- What happens with the maximum valid input?
- What happens with empty input where input is required?
- What happens with invalid format (e.g., letters in a phone number field)?
State Conflicts
- What if the user performs this action twice?
- What if the user navigates back and then forward?
- What if a concurrent action changes the underlying data mid-flow?
External Dependencies
- What if the third-party service is slow?
- What if the third-party service is down?
- What if the API returns an unexpected response format?
User Behavior Patterns
- What if the user uses the back button instead of the in-app navigation?
- What if the user opens the same flow in two tabs?
- What if the user is interrupted mid-flow and returns later?
Permission and Access
- What if the user's session expires mid-flow?
- What if the user doesn't have permission for a step they've already started?
Edge Case Severity Classification
| Severity | Definition | Examples |
|---|
| Critical | Blocks task completion, data loss, incorrect data | Payment processes twice, order not saved |
| Major | Flow fails but recoverable, significant user frustration | Error with no recovery path, unexpected logout |
| Minor | Flow completes but with friction | Misleading copy, unnecessary loading state |
| Cosmetic | Doesn't affect function | Icon misalignment, minor copy inconsistency |
KPI Definition Per Step
What to Measure at Each Step
| Metric Type | Definition | When to Use |
|---|
| Step completion rate | % of users who complete the step out of those who reach it | For critical path steps where abandonment is a risk |
| Time on step | Median time to complete the step | For steps where speed matters or confusion is suspected |
| Error rate | % of attempts that result in an error state | For steps with form input or external dependencies |
| Retry rate | % of users who attempt a step more than once | For steps where first-attempt failure is common |
Drop-Off Point Analysis
For each step, define:
Step: [Name]
Drop-off hypothesis: [Why users might abandon here]
Measurement: [How we'll detect drop-off]
Threshold: [What drop-off rate triggers investigation]
Cross-Journey Interactions
When multiple journeys interact:
- Entry from another journey: What state does the user arrive in?
- State shared between journeys: What data persists across flows?
- Conflicts: Can two journeys create conflicting states?
Best Practices
- Map non-happy paths before happy paths — you'll often find the happy path was incomplete
- Walk the journey yourself — before finalizing, walk each step as a user to find gaps
- Include error messages verbatim — "something went wrong" is not a journey step; the actual message is
- Map the return journey — what does the user experience if they complete and then need to revisit?
- Flag external dependencies explicitly — every third-party touch point is a potential failure mode
- Connect to the PRD — every journey step should map back to a feature in the PRD; if it doesn't, it's either missing from the PRD or scope creep
