---
name: ux-journey-definition
description: "Define a practical, story-first product experience before UI prototyping. Use when you need one canonical artifact that explains what users see, what they can do, and how screens transition."
---

# UX Journey Definition

## Overview

Create one canonical artifact, `experience-story.md`, that captures the product story, main journey, screen-by-screen behavior, and transition mapping. This is the upstream input for `$product-ui-prototyping`.
The artifact must also encode cognition-first decisions so flow order and interaction density reduce user burden.

## Default Output

- `ui-prototypes/<prototype-name>/experience-story.md`
- If the user specifies a different path, follow the user path.

## Workflow

### Audible Notifications (Speak Tool, Required)

- Use the `Speak` tool for key stage-boundary updates so the user does not need to watch the screen continuously.
- Hard rule: speak at both stage start and stage completion for each key stage below (no selective skipping).
- Required speak stages:
  - workflow kickoff (`prototype context acknowledged`, `next stage`),
  - product story + main journey stage (`started`, then draft completed),
  - cognitive load criteria stage (`started`, then criteria drafted),
  - screen stories + alternate/error paths stage (`started`, then draft completed),
  - transition index stage (`started`, then index completed),
  - canonical artifact write stage (`started`, then `experience-story.md` written/updated),
  - quality gate stage (`started`, then `Pass`/`Needs fixes` result),
  - handoff-ready stage for `$product-ui-prototyping` (`started`, then ready status).
- Speak trigger policy:
  - do not skip required stage-boundary speak events,
  - for completion events, speak only after milestone content is physically written,
  - do not speak for partial drafts between required stage-boundary events,
  - batch close-together milestone updates into one short message.
- Keep each spoken message short (1-2 sentences), status-first, with one clear next step.
- If the `Speak` tool fails or is unavailable, continue workflow and provide the same update in text.
- Do not speak secrets, tokens, or full sensitive payloads.

### 1) Capture Product Story

Write one short paragraph:
- who the user is,
- what they are trying to achieve,
- what success looks like.

Keep this concrete and product-facing.
- Speak completion after product story draft is physically written.

### 2) Write Main Journey (Happy Path)

Write a numbered flow from entry to success.
Each step should include:
- what the user does,
- what the system does,
- which `screen_id` is involved.

Prioritize one critical flow first before expanding.
- Speak completion after main journey draft is physically written.

### 3) Define Cognitive Load Criteria (Required)

Before writing detailed screen behavior, define a short cognition-first rubric for this product:
- learning order strategy (what comes first and why),
- connection strategy (group by semantic/stem linkage where possible),
- chunking limits (items per step/screen),
- interference controls (what confusing patterns are delayed),
- progression policy (when to unlock complexity).

Keep this practical and measurable so it can be used as a review gate.
- Speak completion after cognitive-load criteria are physically written.

### 4) Write Screen Stories

For each screen, describe behavior in plain language with stable IDs.

Required shape:
- `screen_id`
- user arrives from
- user sees
- user can do (`action_id`)
- system behavior for each action
- cognitive objective (what mental burden this screen reduces)
- cognition controls (chunking, progressive disclosure, contrast/clarity choices)
- states to prototype (`default`, `loading`, `success`, `error`, `empty` when applicable)
- Speak completion after screen stories are physically written.

### 5) Capture Alternate/Error Paths

Document only meaningful branches:
- validation failures,
- empty/no-results states,
- recoverable errors.

For each branch, state:
- trigger/condition,
- what user sees,
- recovery action and destination.
- Speak completion after alternate/error paths are physically written.

### 6) Build Transition Index

Create a single transition table that links interactions to movement.

Columns:
- `transition_id`
- `trigger`
- `from_screen`
- `to_screen`
- `expected_feedback`

Use IDs consistently across the whole document.
- Speak completion after the transition index is physically written.

### 7) Record Blocking Questions

List only blockers that can change behavior or flow.
Do not include cosmetic/open-ended discussion items.

## Canonical Artifact Template

Use this structure in `experience-story.md`:

```markdown
# Experience Story: <prototype-name>

## 1) Product Story
<one short paragraph>

## 2) Main Journey
1. ...
2. ...

## 3) Cognitive Load Criteria
- Learning order: ...
- Connection strategy: ...
- Chunking limit: ...
- Interference control: ...
- Progression policy: ...

## 4) Screen Stories

### screen_id: <screen_id>
- User arrives from: ...
- User sees:
  - ...
  - ...
- User can do:
  - `<action_id>`: ...
- System behavior:
  - when `<action_id>` -> <feedback> -> go to `<next_screen_id>`
- Cognitive objective: ...
- Cognition controls:
  - chunking: ...
  - progressive disclosure: ...
  - clarity guardrails: ...
- States to prototype: default, loading, success, error, empty

## 5) Alternate And Error Paths
- If <condition>, show <state/message>, then user can <recovery action>.

## 6) Transition Index
| transition_id | trigger | from_screen | to_screen | expected_feedback |
| --- | --- | --- | --- | --- |
| ... | ... | ... | ... | ... |

## 7) Blocking Questions
- <question> (owner: <name>)
```

## Practical Rules

- Keep it practical and short. Avoid heavy theory.
- No `out-of-scope` section by default.
- Focus on behavior and navigation, not design tokens.
- Keep each screen section to 5-8 bullets.
- Every action must define both feedback and next destination.

## Quality Gate

- One clear happy path exists from entry to success.
- Every major trigger maps to a target screen/state.
- Screen IDs and transition IDs are consistent.
- Error and empty states include recovery actions.
- The learning sequence explicitly minimizes cognitive burden (simple -> connected -> complex).
- Early modules prioritize semantic/stem-connected content before higher-interference pattern groups.
- Each screen declares its cognitive objective and concrete burden-control mechanisms.
- The document can be directly used by `$product-ui-prototyping`.
- Speak quality-gate result after validation completes.

## Handoff To Prototyping

When visual prototyping is requested next, invoke `$product-ui-prototyping` with:
- `ui-prototypes/<prototype-name>/experience-story.md`
- product constraints from this document
- chosen platform (`web`, `ios`, `android`)

Then generate state images, flow maps, and viewer artifacts based on the transition index and screen stories.
- Speak handoff-ready completion after `experience-story.md` is written/updated.