user-journey

name	user-journey
description	Build a persona-grounded user journey map for a product flow
argument-hint	[flow or task the user is trying to complete]

User Journey

You help map a user journey for a specific task or flow. The output is a markdown journey artifact that names the persona, walks through stages, and highlights friction, emotion, and opportunities.

Input

The user provides via $ARGUMENTS:

• A short description of the task or flow (e.g., "first-time API integration", "renewing a subscription", "handling a support escalation")

Workflow

1. Pick the persona

Read research/personas/ to see what personas exist.

If one persona clearly matches: confirm with the user - "I'll ground this journey in [[persona]]. OK?"

If multiple could match or none exists: ask the user which persona to use via AskUserQuestion, offering personas from research/personas/ plus an "Other - I'll describe it" option.

If no personas exist yet: prompt the user to run /personalize --deep or describe the persona in a short paragraph. Build the journey with an inline persona description at the top.

2. Define the task and its boundaries

Clarify in ONE AskUserQuestion round (skip any that are already answered):

• Starting point: what triggers the user to begin this journey? (A specific event, not "they want to use the product".)
• End state: what does "done" look like? (A specific measurable outcome.)
• Context: time pressure, skill level, tools available.
• Happy path or full path: do we map the ideal flow or include edge cases?

3. Map the journey

Produce a table-and-prose journey map with these columns:

Stage	What the user does	What the user thinks	What the user feels	Friction / opportunity

Keep stages at the right level of granularity - for most journeys, 5-8 stages is the sweet spot. Fewer misses detail; more turns into a task list.

For each stage:

• What the user does: concrete action.
• What the user thinks: internal voice, first-person.
• What the user feels: emotion in one or two words.
• Friction / opportunity: what's slow, confusing, or a moment of truth - and what could be improved.

Use specific, first-person voice ("I paste my API key and...") over generic ("The user enters credentials...").

4. Highlight the 2-3 biggest moments of truth

A "moment of truth" is a stage where the user's experience makes or breaks their trust in the product. Below the table, call out the 2-3 most critical:

### Moments of truth

1. **[Stage name]**: Why it's critical, what good looks like, what bad looks like.
2. ...

5. Propose opportunities and experiments

In the last section, list 3-5 concrete things to improve the journey. For each:

• What the opportunity is.
• What experiment would validate the fix.
• Rough effort (small / medium / large).

These feed into /opportunity-solution-tree or a follow-up epic.

6. File location and naming

• Folder: research/journeys/. Create if it doesn't exist.
• Filename: YYYY-MM-DD - [Persona] - [Flow].md. Example: 2026-04-20 - Dana (Backend Dev) - First API Integration.md.
• Frontmatter: tags: Journey, persona: [[persona file]], created: YYYY-MM-DD.

7. Link the journey

• Daily journal: under ## Notes.
• Related epic: if this journey was built for a specific epic, add a link in that epic's ## Breakdown > Scope section.
• Persona file: append a reference to the journey at the bottom of the persona's Research Sources section.

8. Output summary

✅ Journey mapped: [[YYYY-MM-DD - Persona - Flow]]
✅ Linked in today's journal
[if epic] ✅ Linked in [[Epic]]

Persona: [[persona]]
Stages: [N]

🎯 Moments of truth:
1. [Stage name]
2. [Stage name]

💡 Top opportunity: [One-line summary]

Next step: run `/opportunity-solution-tree` to explore solutions for the top opportunity.

Notes

• First-person voice beats third-person. Readers feel the journey more when it's "I" instead of "the user".
• Emotion matters. A journey map without emotion is just a flowchart.
• One persona per journey. If a journey serves multiple personas, the stages and friction are usually different - build a separate map per persona and compare.
• Not a full feature spec. The journey highlights where the problems are; the epic describes what to build about them.