PRD → User Journeys

Turn a PRD into a complete user journey/flow doc: real end-to-end journeys (not per-story fragments), every edge case placed where its consumer will find it, and a screen inventory the downstream steps pick up.

Where this sits in the flow: it's the step after the PRD and before the design step — prd/prd.md → journeys.md → design → brand → prototype → Blueprint. The screen inventory it produces is load-bearing downstream: the stitch-prompt step designs those screens, the claude.ai JSX prototype builds them, and the Blueprint's frontend change-list + chunk map (§7/§8) trace back to them. A missing or vague screen here surfaces as a hole three steps later.

Interview-first: PRDs always have holes. A wrong guess about who the user is or what happens on failure poisons every downstream artifact, so resolve gaps with the user before drafting — never draft on silent assumptions.

Phase 0: Locate inputs

1. Find the PRD (prd/prd.md, or wherever the user points).
2. Read the PRD fully, plus any notes/docs it references or that sit alongside it and are clearly related.
3. Check for an existing journeys doc next to the PRD (journeys.md or <prd-basename>.journeys.md). If found → update mode (see below). If not → fresh generation.

Output path: same directory as the PRD. Name it journeys.md; if the directory holds multiple PRDs, use <prd-basename>.journeys.md so pairing stays self-evident.

Phase 1: Gap interview

Walk this checklist against the PRD. For each item the PRD already answers, skip it — a thorough PRD means a short interview. For each gap, ask the user.

1. Personas + goals — who uses this, and what is each trying to accomplish. Hard-blocking: do not draft anything until this is resolved.
2. Entry points — how users arrive at each journey (nav, deep link, notification, cold open).
3. Auth/permissions — what's gated; what an unauthenticated/unauthorized user hits at a gated step.
4. Failure handling — payment/network/validation failures: retry policy, fallback destination.
5. Empty & first-run states — zero-data experience per major screen.
6. Concurrency/staleness — two tabs, expired session, data changed underneath (only if the PRD implies it).
7. Exit & interruption — abandonment mid-flow: what's saved, what's lost, resume behavior.
8. Notifications/async re-entry — anything that pulls the user back into a flow later.
9. Platform constraints — mobile/desktop divergence, offline (only if the PRD implies it).

Interview rules:

• One question at a time. Multiple questions at once are bewildering; wait for each answer.
• Always include a recommended answer with the one tradeoff that matters. The user should be able to reply "yes" to move fast.
• If the user says "you decide" or defers, choose, and log it as a decision marked (deferred to skill).
• Record every Q&A — it becomes the ## Decisions section of the doc.

Phase 2: Draft the doc

Decomposition

Journeys = persona × top-level goal (job-to-be-done), e.g. "New user: first booking", "Returning user: manage booking". Each journey is an end-to-end session slice, not a user-story fragment — real sessions cross many stories, and per-story flows duplicate shared segments like onboarding.

Coverage guarantee comes from the story traceability table: every user story in the PRD maps to the journey(s) that cover it. A story with no journey is a caught gap — go back to Phase 1 and resolve it before finishing.

Edge cases: two-tier rule

Test: does the edge case navigate the user somewhere else?

• Yes → inline. It's a branch in that journey's Mermaid diagram + prose (payment fails → retry loop → fallback screen). These get reviewed by humans reading the flow.
• No → state matrix. Per-screen states (loading, empty, error+retry, permission denied) live in the screen inventory's state matrix. These get consumed by whoever builds the screens.

Never bury a flow-changing case in the appendix, and never bloat a diagram with 30 per-screen state nodes.

Doc template

Use this structure exactly:

# <Product> — User Journeys

Source PRD: <relative path> (<date generated/updated>)

## Personas
One short paragraph each: who they are, what they want.

## Journeys

### J1 — <Persona>: <Goal>
**Entry points:** <how they arrive>

​```mermaid
flowchart TD
    <screens as nodes, decisions as diamonds, edge-case branches labeled>
​```

**Steps:** numbered prose walkthrough. Inline edge-case branches called out
where they occur, with the condition and destination.

**Exit states:** success exit(s) + abandonment/interruption behavior.

### J2 — ...

## Story Traceability

| Story | Journey(s) | Notes |
|-------|------------|-------|

Every PRD story appears here. No orphans.

## Screen Inventory

One entry per screen the journeys imply. This is the handoff surface for the
design + prototype steps and the Blueprint's frontend section — loose format, no rigid schema.

### S1 — <Screen name>
**Purpose:** one line. **Appears in:** J1, J3.
**Contents:** what's on it (elements/data, not visual design).

| State | Behavior |
|-------|----------|
| Loading | |
| Empty | |
| Error | + retry path |
| <permission/other as relevant> | |

## Decisions

| # | Question | Answer | Date |
|---|----------|--------|------|

Interview Q&A log. Doubles as design rationale and powers update mode.

Mermaid conventions: flowchart TD, one diagram per journey, screens as rectangles, decision points as diamonds, edge-case branches with labeled arrows (-->|payment fails|). Keep each diagram readable — if a journey needs more than ~20 nodes, it's probably two journeys.

Quality check before finishing

• Every PRD user story appears in the traceability table.
• Every screen referenced in any diagram exists in the screen inventory.
• Every screen has its state matrix filled (or a stated reason a state doesn't apply).
• Every interview answer is in ## Decisions.
• No silent assumptions anywhere — anything not from the PRD or the interview doesn't belong in the doc.

Update mode

When a journeys doc already exists and the PRD changed:

1. Read the existing doc, especially ## Decisions.
2. Re-walk the Phase 1 checklist against the new PRD. Skip anything a logged decision already answers.
3. Flag contradicted decisions — if a logged answer now conflicts with the PRD, ask the user which wins. Never silently keep a stale decision, never silently overwrite one.
4. Interview only on genuinely new gaps.
5. Patch the doc surgically: touch only journeys/screens/rows the PRD change affects. Preserve the user's manual edits everywhere else.
6. Append new Q&A to ## Decisions; update the source-PRD date line.