# User Journey

> Build a persona-grounded user journey map for a product flow

- Skill: `aleksander-dytko/user-journey` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aleksander-dytko/user-journey`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aleksander-dytko/user-journey/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aleksander-dytko (https://skillmd.com/u/aleksander-dytko)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aleksander-dytko/user-journey

---


# 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.