walkthrough

name	walkthrough
description	Task-based evaluation of a real interface — take one job from the JTBD corpus, attempt it step by step as the person who has it, and record where the attempt breaks. Answers "can someone actually complete this?", which inspection and reaction methods do not. Runs a cognitive walkthrough (four questions per step) against a live URL, a prototype, screenshots, or the code, and reports task success against the outcome it was derived from. Use when you have a task and something operable to attempt it on. Triggers on walkthrough, cognitive walkthrough, task analysis, "can a user actually do this", "test this task", "where do people get stuck", "walk through the signup flow", "test this on mobile", "drive it in the browser", "пройди сценарий".
handoffs	[{"to":"layout-rules","when":"a mobile-tier finding is a tap target or horizontal scroll"},{"to":"design-tokens","when":"a walkthrough finding is a contrast failure"}]
accepts	[{"from":"jtbd"},{"from":"nielsen-heuristics"},{"from":"prototype"}]

Walkthrough

Announce at start: "I'm using the humane:walkthrough skill to attempt this task as the person who has it."

Inspection asks whether an interface obeys principles. Reaction asks how words land. Neither asks the question that decides whether the product works: can this person, with this goal, get through?

A walkthrough answers that by attempting the task — one concrete task, one concrete person, one step at a time — and recording exactly where the attempt would break.

When to invoke — and when not

Reach for this when you have a task and something to attempt it on.

You want	Skill
Can someone complete this task?	this skill
Does the interface violate usability principles?	nielsen-heuristics
How does this copy land with strangers?	respondent-panel
Would an expert stakeholder object to this document?	persona-review
Did the change actually improve things?	before-after (feed it these results)

Do not run this on a spec or a description. A walkthrough needs something to operate. If all you have is a document, nielsen-heuristics design-risk mode is the honest substitute — say so and switch.

Step 1 — Derive the task from the corpus, not from the interface

The most common way this method fails is walking the flow the designer built instead of the job the person has. Guard against it by taking the task from outside the interface.

1. Read <corpus_root>/<slug>/jtbd.json — corpus_root is the setup setting, default ~/jtbd; read the configured value, not the default. Prefer a task derived from an odi.outcomes[] entry — those already carry a stage (one of define/locate/prepare/confirm/execute/monitor/modify/conclude) and a touch (the surface it lives on). An underserved outcome (high importance, low satisfaction) is the highest-value thing you can walk.
2. Write the task as the person's goal, in their words, with no interface nouns in it. "Find out what I spent on models last week" — not "open the billing dashboard and apply a date filter." If your task statement names a button, you have already assumed the answer.
3. Name the actor and their entry state. Who they are, what they already know, what they have already done, where they arrive from, on what device. Use the corpus actor and jtbd.situation. First-time and returning users walk different paths through the same screens — pick one and say which.
4. State the success condition — the observable thing that is true when the job is done. This is what "task success" is measured against, and it must be decided before the walk.

If no corpus exists, ask the user for the task and the actor, and record in the output that the task was supplied rather than derived. That is a weaker basis and the reader should know.

Step 2 — Pick the mode honestly

Mode	Artifact	What you can claim
Driven	Live URL or running app	Strongest. You observed real behavior, real states, real errors.
Prototype	Clickable prototype, or an ordered set of screenshots	You observed intended behavior. Anything not prototyped is unknown, not working.
Static	Screenshots with no flow	You can assess each step's affordances, not the transitions between them.
Code	Source only	You can reconstruct the intended flow. You cannot claim what renders. Weakest — pair it with one of the above whenever possible.

Announce the mode and its ceiling in the output. Never let a code reading masquerade as an observation.

Driven mode has a procedure — references/driven.md. It owns the browser tool ladder (agent-browser CLI first, it emulates real devices), the device matrix (mobile tier mandatory when the walk feeds a review full pass), the screenshot-per-step evidence contract, and the mode gate: a claimed mode is downgraded to what the captured evidence supports, never argued back up. review and nielsen-heuristics drive by that same file — do not restate it for them.

Step 3 — Walk it, one step at a time

A step is one decision the person makes, not one screen. A screen with three plausible next actions is three steps' worth of decision.

At every step, answer the four cognitive-walkthrough questions. Each gets a yes/no and a reason:

1. Will they try to achieve this effect? Does the person, at this moment, actually want to do this sub-goal — or is it something the system needs and they don't care about?
2. Will they notice the control is available? Is it visible, in the scan path, not below the fold, not hidden behind a hover or a menu?
3. Will they connect the control to the effect they want? Does the label, icon, or position say what it does in their vocabulary? (This is where habit from the switch forces bites: they are looking for the old product's word.)
4. Will they see that progress was made? After acting, is there feedback that they got closer — or does the system go quiet and leave them guessing?

Any "no" is a break. Record it with:

• the step number and what the person was trying to do,
• which of the four questions failed,
• the evidence locator (screenshot, URL, file:line, or the exact element),
• what the person most likely does next: recover, take a wrong path, or abandon.

That last field is what makes a walkthrough actionable. A break the user recovers from in one second is not the same defect as one that sends them into a dead end, even when the same question failed.

Do not fix as you go. Walk the whole task first. Stopping to redesign at the first break hides everything downstream of it, and downstream breaks are often the worse ones.

Step 4 — Walk the unhappy paths too

A task that only works when nothing goes wrong is not a task that works. Once the happy path is walked, walk at least the applicable ones:

• empty — first run, nothing created yet
• error — the request fails, the input is rejected, the connection drops
• slow — the response takes 10 seconds; what does the person see and do?
• interrupted — they navigate away and come back, or reload mid-task
• permission — they lack access to something the path requires

Reloading mid-task is the cheapest high-yield check there is: if state does not survive it, layout-rules rule 16 is violated and the task is fragile in a way no happy-path walk reveals.

Step 5 — Report

Task and basis

The task in the person's words, the actor and entry state, the success condition, the corpus outcome it came from (with its importance/satisfaction if scored), the mode, and the mode's ceiling. In driven mode, also the tool rung and the device tiers walked (references/driven.md); every finding names the tier(s) it was observed on, and a tier not walked is a tier not claimed.

Walk

One row per step. Keep the steps the person passed — a walkthrough that lists only failures cannot show how far they got before breaking.

#	Goal at this step	Q1 try	Q2 notice	Q3 connect	Q4 feedback	Evidence	Likely next
3	Narrow to last week	yes	no	—	—	step-3.png, date control below fold	scrolls, or gives up on filtering

Findings

The breaks, consolidated and ranked — one root cause per row, listing every step it affected:

Severity	Step(s)	Question	Location	Before	After	Why

Step(s) and Question are this skill's two additions to the shared five-column findings table — they carry where in the walk the break happened and which of the four questions failed, which no other domain has. Under review, drop them: that skill owns the consolidated format, and a wider table cannot merge with the others. Fold the step and question into Why instead of losing them.

• HIGH — the task cannot be completed, or completes wrongly without the person noticing.
• MEDIUM — the task completes, but through recovery, a wrong turn, or unreasonable effort.
• LOW — friction that a person absorbs without deviating.

Cap at 15; never pad. Route each finding to its owner rather than solving it here: wording to ux-writing, a defect class to layout-rules, a principle violation to nielsen-heuristics, a contrast measurement to design-tokens.

Considered but Rejected

Two to five steps that looked like breaks and were not, with the reason — the convention is learnable, the affordance is discoverable in one scan, the recovery is immediate.

Verification

Every state actually reached, and how. Unhappy paths that could not be triggered are Not verified, with what remains — never reported as failures. "I could not make the payment fail" is a coverage gap, not a finding.

Verdict

Both of these:

• Task success: Completed · Completed with recovery · Completed incorrectly · Blocked at step N.
• Overall: Block (any HIGH), Needs changes (only MEDIUM/LOW), Approve (no actionable findings and the claimed coverage was verified).

What this method is and is not

This is an analytical walkthrough performed by an agent reasoning about a person, not a usability test with a real person. It reliably surfaces missing affordances, vocabulary mismatches, silent failures, and dead ends — cheaply and before anyone is recruited. It cannot tell you how long something takes, how frustrating it feels, or what people do that no one anticipated.

Never report it as a usability study, never attach a task-success percentage to it, and never let it be the reason not to watch one real person try. Two evaluators walking the same task independently find noticeably more than one; if that is affordable, do it and merge.

Handoff

• Breaks fixed → re-walk the same task, same actor, same success condition, so the comparison is clean.
• Task now completes → before-after can use the walk as the evidence that the change worked. A before/after grid backed by a blocked-then-completed task is a claim with a receipt.
• Outcome still underserved after the fix → back to jtbd; the problem may be the job, not the flow.