walkthrough
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", "пройди сценарий".
glebis · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add glebis/humane-agentic-design --skill walkthroughAbout this skill
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
- from: sound-effects
- from: semantic-micro-interactions
- from: narrative-scrollytelling
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.
- Read
<corpus_root>/<slug>/jtbd.json—corpus_rootis thesetupsetting, default~/jtbd; read the configured value, not the default. Prefer a task derived from anodi.outcomes[]entry — those already carry astage(one of define/locate/prepare/confirm/execute/monitor/modify/conclude) and atouch(the surface it lives on). An underserved outcome (high importance, low satisfaction) is the highest-value thing you can walk. - 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.
- 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
actorandjtbd.situation. First-time and returning users walk different paths through the same screens — pick one and say which. - 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:
- 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?
- 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?
- 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
habitfrom the switch f