JOURN-004: Spec — JOURNEY_INDEX.csv (system-wide journey registry) #33
Description
Problem We Are Solving
The system has no single place that answers: "What user journeys does this product have, and what is the health of each?"
Today:
- Journeys live as Figma pages (designer knows)
- Journeys live as GitHub epics (project manager knows)
- Contract coverage is in CI logs (tech lead knows)
- No single artifact shows all three together
This is exactly the problem that CONTRACT_INDEX.yml solves for contracts. One file, one glance, complete picture. Journeys need the same thing.
Why CSV not YAML: The CONTRACT_INDEX.yml is YAML — suitable for contract metadata that has deep nested structure. Journey index is flat: one row per journey, fixed columns. A designer or PM can open it in Excel/Sheets and understand it immediately. CSV is the right format for a flat registry a non-developer should be able to read.
What We Are Building
docs/journeys/JOURNEY_INDEX.csv
A checked-in CSV file, updated automatically by CI on every journey:sync run.
Format
journey_id,display_name,persona,epic_issue,figma_file_id,figma_page,status,step_count,readiness_pct,owner,last_synced
ONBOARDING,New User Onboarding,New User,#100,abc123,Journey: ONBOARDING,active,5,51,dom@team.com,2026-02-20T14:32:00Z
REACTIVATION,Returning User Flow,Returning User,#101,abc123,Journey: REACTIVATION,active,3,80,dom@team.com,2026-02-20T09:00:00Z
BILLING_UPGRADE,Upgrade to Pro,Existing User,#102,abc123,Journey: BILLING,in_progress,4,25,pm@team.com,2026-02-19T16:00:00Z
SETTINGS,Account Settings,All Users,#103,,planned,0,0,,Column Definitions
| Column | Owner | Description |
|---|---|---|
journey_id |
System | Machine key. Matches Figma page name after "Journey: " and GitHub epic label |
display_name |
Designer/PM | Human name. Appears in observation deck header |
persona |
Designer | Primary user type. Used for filtering in observation deck |
epic_issue |
System | GitHub epic issue number. The journey's home |
figma_file_id |
Designer | Figma file ID. Populated when journey:sync runs with --figma |
figma_page |
System | Figma page name. Must match "Journey: JOURNEY_ID" convention |
status |
System | active / in_progress / planned / deprecated |
step_count |
System | Total steps currently ticketed |
readiness_pct |
System | 0–100. Updated by CI after every journey:annotate run |
owner |
PM/Designer | Who is responsible for keeping this journey healthy |
last_synced |
System | ISO 8601 UTC. When journey:sync last ran successfully |
Lifecycle
Adding a journey: Anyone adds a row manually with journey_id, display_name, persona, epic_issue, owner, status=planned. All system-managed columns start empty and are populated by journey:sync.
Updating: journey:sync and journey:annotate update system-managed columns (step_count, readiness_pct, figma_file_id, figma_page, last_synced, status). Human-managed columns (display_name, persona, owner) are never overwritten by automation.
Deprecating: Set status=deprecated manually. CI will no longer run checks on deprecated journeys. Epic body shows deprecation notice.
Schema Validation Test
A test in tests/schema/journey_index.test.js validates:
- All required columns present in header
- journey_id values are uppercase, no spaces
- status values are within allowed enum
- readiness_pct is 0–100 integer
- epic_issue format is #NNN
- last_synced is valid ISO 8601 when present
Relation to CONTRACT_INDEX.yml
CONTRACT_INDEX.yml lists all contracts (what rules the code must follow).
JOURNEY_INDEX.csv lists all journeys (what paths users take through the product).
Together they answer: "What rules do we enforce and what user flows do those rules protect?"
Acceptance Criteria
- JOURNEY_INDEX.csv created at docs/journeys/JOURNEY_INDEX.csv
- journey:sync updates system-managed columns on every run
- Human-managed columns (display_name, persona, owner) never overwritten
- Schema validation test in tests/schema/journey_index.test.js
- Example file committed with at least 3 example journeys (including one planned with no Figma yet)
- verify-setup.sh checks for JOURNEY_INDEX.csv and reports its existence
Depends on
JOURN-002 (journey:sync populates system columns)