User Walkthrough

---
name: user-walkthrough
description: Walk one complete journey against the running build with a declared knowledge state, name observable UX failure patterns, and refuse to invent whether a person would want the product.
when_to_use: Use when pnpm design:route includes user-walkthrough, or the owner asks whether a journey works end to end.
---

# User walkthrough

Screen reviews do not prove a journey. When `pnpm design:route` includes this
skill, walk its declared scope: the changed path for a local journey change, the
agent-handoff path for a handoff change, or the continuous north-star path for a
new surface.

## Authority and limit

Judge facts that live in the artifact: vocabulary, next-step visibility, control
discoverability, feedback, perceived reversibility, waiting state, missing paths,
and visible craft. Each can be proven by pointing at the screen.

Do not claim facts that live in a person's mind: whether they want it, will return,
recommend it, or pay. Simulated users mispredict real people inconsistently. “No
observable stall” does not mean “they like it.” Demand, retention, and willingness
come only from real people.

## Name patterns, not emotions

Every finding carries a reusable pattern name. “This person will feel frustrated”
is invention; “dead-end CTA—the primary button opens an empty destination” is a
checkable pattern.

Common patterns:

| Pattern | Definition |
|---|---|
| Dead-end CTA | the strongest action leads nowhere useful |
| Implementation-language label | the label describes program work, not the user's outcome |
| Gate before value | the product requires something before showing why it matters |
| Silent wait | work is happening with no visible progress |
| Unknown reversibility | a risky-looking action shows no undo or cancellation path |
| Builder vocabulary leak | internal developer terms appear on the user surface |
| Missing next step | the screen does not say what follows the completed action |

Name and define a new repeatable pattern when needed. Repeated patterns in the
decision ledger may deserve a product rule.

## Declare the walker

Use only knowledge state, situation, and concern. Do not invent demographic or
emotional backstory.

Default:

```text
Knows: uses Claude Code daily; maintains AGENTS/CLAUDE Markdown; comfortable with Git.
Does not know: Atlas; product use of “ontology”; graph databases.
Context: technical lead on a 2–10 person team, received a link while doing other work, meeting in 10 minutes.
Cares about: agents losing context, software touching local files, and the ability to leave later.
```

Make the knowledge gap real by using a fresh agent that has read none of this
repository. Give only the profile, one task sentence, and starting URL. The
walker records what was visible, clicked, expected, and observed; it does not
judge the product.

## Four questions at every step

1. **Goal:** was the required action understandable?
2. **Discovery:** was the relevant control visible?
3. **Connection:** did its label describe the outcome in the walker's language?
4. **Confirmation:** after action, did visible state confirm progress?

Record `[step · screen · failed question · elapsed time · evidence]`.

## Two journeys

Choose A, B, or both from the routed task. These are alternatives, not two
mandatory journeys. Record local completion time for a changed-path walk; use
link-to-first-citation timing only for the north-star or agent citation task.

**A. Agent journey is a real user measurement.** A plain coding-agent session
with only Atlas MCP receives: “Explain this repository's structure and cite vault
nodes.” Measure from opening the link to the first accurate citation. The tested
population is the product's actual agent user.

**B. Human journey is a usability inspection.** Use the knowledge profile and a
running static export or installed app to complete the task end to end. It still
cannot prove desire.

For every human journey, capture the actual app/window at the changed or failed
step as in the `/design-build` §0-B render loop (tree + screenshot paths), and
record the visible control that owned the next action. Browser screenshots
support measurement; they do not replace it.

## Where results go

- Stalls become direct-use evidence for `/po-pass` and the `reviewer`'s
  `evidence` lens.
- Hierarchy and interaction findings feed the `reviewer`'s `attention` and
  `reversibility` lenses.
- A clean walkthrough does not justify “Build and verify”; it proves only that
  this journey exposed no named stall.

## Output

```md
## User walkthrough — <task>

**Outcome**: completed | failed at <step> — <what the walker could not do, in one line>

**Walker**: <knowledge · context · concern> · **walker**: fresh subagent id <id>
**Journey**: A agent / B human / both
**Build**: <URL or installed app · commit>
**Time**: <scoped task duration; north-star citation time only when applicable>

| Step | Screen | Failed question | Time | Evidence |
|---|---|---|---:|---|
| … | … | goal/discovery/connection/confirmation | … | screenshot or log |

**Stalls, highest severity first**: …
**Exit point**: <where and why the task was abandoned, if any>
**What the artifact did not say**: <internal label, missing next step, invisible state>
**Not claimed**: whether this person wants, returns to, or recommends the product.
```