User Journeys Skill
Load with: base.md + playwright-testing.md
For defining and testing real user experiences - not just specs, but actual flows humans take through your application.
Philosophy
Specs test features. Journeys test experiences.
A feature can pass all specs but still deliver a terrible experience. User journeys capture:
- How users actually navigate (not how we think they should)
- Emotional states at each step (frustrated, confused, delighted)
- Recovery from mistakes (users will make them)
- Real-world conditions (slow networks, interruptions, distractions)
Journey Documentation Structure
_project_specs/
├── journeys/
│ ├── _template.md # Journey template
│ ├── critical/ # Must-work journeys (revenue, core value)
│ │ ├── signup-to-first-value.md
│ │ ├── checkout-purchase.md
│ │ └── login-to-dashboard.md
│ ├── common/ # Frequent user paths
│ │ ├── browse-and-search.md
│ │ ├── update-profile.md
│ │ └── invite-team-member.md
│ └── edge-cases/ # Error recovery, unusual paths
│ ├── payment-failure-retry.md
│ ├── session-timeout-recovery.md
│ └── offline-reconnection.md
Journey Template
# Journey: [Name]
## Overview
|-----------|-------|
| **Priority** | Critical / High / Medium |
| **User Type** | New / Returning / Admin |
| **Frequency** | Daily / Weekly / One-time |
| **Success Metric** | Conversion rate, time to complete, drop-off rate |
## User Goal
What is the user trying to accomplish? Write from their perspective.
> "I want to [goal] so that I can [benefit]."
## Preconditions
- User state (logged in, has subscription, first visit)
- Data state (has items in cart, has team members)
- Environment (mobile, desktop, slow connection)
## Journey Steps
### Step 1: [Entry Point]
**User Action:** What the user does
**System Response:** What they should see/experience
**Success Criteria:**
- [ ] Page loads in < 2 seconds
- [ ] Primary CTA is immediately visible
- [ ] User understands what to do next
**Potential Friction:**
- Slow load time → Show skeleton/loader
- Unclear CTA → A/B test copy variations
---
### Step 2: [Next Action]
**User Action:** ...
**System Response:** ...
**Success Criteria:**
- [ ] ...
**Potential Friction:**
- ...
---
## Error Scenarios
### E1: [Error Name]
**Trigger:** What causes this error
**User Sees:** Error message/state
**Recovery Path:** How user gets back on track
**Test:** How to verify recovery works
## Metrics to Track
- Time to complete journey
- Drop-off rate at each step
- Error rate and recovery rate
- User satisfaction (if surveyed)
## E2E Test Reference
Link to Playwright test: `e2e/tests/journeys/[name].spec.ts`
Critical Journey Examples
Signup to First Value
# Journey: Signup to First Value
## Overview
|-----------|-------|
| **Priority** | Critical |
| **User Type** | New |
| **Frequency** | One-time |
| **Success Metric** | % reaching "aha moment" within 5 min |
## User Goal
> "I want to try this product quickly to see if it solves my problem."
## Preconditions
- First visit to site
- No account
- Came from landing page or ad
## Journey Steps
### Step 1: Landing Page
**User Action:** Clicks "Get Started Free" or "Try Now"
**System Response:** Signup form appears (modal or new page)
**Success Criteria:**
- [ ] CTA visible above fold
- [ ] No distracting elements
- [ ] Clear value proposition visible
**Potential Friction:**
- Too many form fields → Reduce to email + password only
- Social login missing → Add Google/GitHub options
### Step 2: Account Creation
**User Action:** Enters email and password (or uses social login)
**System Response:**
- Creates account
- Sends verification email (don't block on it)
- Redirects to onboarding
**Success Criteria:**
- [ ] Account created in < 3 seconds
- [ ] No email verification wall (verify later)
- [ ] Clear next step shown
**Potential Friction:**
- Email already exists → Offer login link
- Weak password → Show requirements inline, not after submit
### Step 3: Onboarding (Quick Win)
**User Action:** Completes 1-2 setup questions
**System Response:**
- Personalizes experience
- Shows progress indicator
- Leads to first action
**Success Criteria:**
- [ ] Max 3 questions
- [ ] Skip option available
- [ ] < 60 seconds total
**Potential Friction:**
- Too many questions → User abandons
- No skip option → User feels trapped
### Step 4: First Value (Aha Moment)
**User Action:** Completes core action (creates first X, sees first result)
**System Response:**
- Celebrates success
- Shows value delivered
- Suggests next step
**Success Criteria:**
- [ ] User experiences core value
- [ ] Completion feels rewarding
- [ ] Clear path to continue
## Error Scenarios
### E1: Email Already Registered
**Trigger:** User tries existing email
**User Sees:** "Already have an account? Log in or reset password"
**Recovery Path:** Click to login or reset
**Test:** `signup-existing-email.spec.ts`
### E2: Social Login Fails
**
