Persona walkthrough

Persona walkthrough

The principle

A walkthrough does not measure whether the code is right. It measures whether the person the product claims to serve can reach the end.

This is not one more layer of testing. It is the layer the others cannot reach. The four verification skills that ship next to this one (behavior-spec, spec-coverage, audit-tests, review-cross) prove that the code does what the spec says. None of them asks whether the spec says what the person needs.

The case that closes the argument, from the product this skill was born in:

• The onboarding writes the answer under the key onboarding.profile.v1, in a field named occupation.
• The lesson reads the key onboarding:profile, and looks for a field named profession.

Each side passes its own test. Mutation testing cannot find it, because there is no mutant for an agreement nobody wrote down. Cross review cannot find it, because no numbered rule was betrayed. And the product asks for your occupation promising "just so the examples look like you", then hides the only example that had your face on it.

Only somebody crossing both sides as a human being finds that. In the original the drift was between a field name in one language and its translation in another, which is the version you are most likely to meet in a localized product.

The walkthrough discovers the rule nobody wrote. The gate keeps it from coming back.

When to use, when not to use

Use for: first contact, the absolute beginner path, a journey that crosses several modules, an onboarding audit, and any time a written promise of the product needs to be collected against what the screen actually does.

Do not use for:

• Designing or scoring a question in your survey or diagnostic. That is a different job, and it belongs to whoever owns the instrument.
• Deciding to build, cut or prioritise. That is a product decision, and this skill has no opinion on it.
• Finding a unit bug. A unit test finds it cheaper and faster.

What this skill does not replace

Continuous discovery asks for a session every week watching a real layperson cross the product. Some practitioners ask for two or three a week. If your repository has zero interviews with a non technical user, a simulated walkthrough does not fix that, and pretending otherwise is the failure this skill exists to catch.

A simulated walkthrough proves what breaks, what lies and where the vocabulary fails, with a screen and with a cause. It never proves that the person wants it, would pay for it, or would come back tomorrow.

Provenance limits what you are allowed to claim. That is a rule here, not a style preference. See references/anatomy-of-a-persona.md.

Mandatory grounding

Before opening the app, read:

1. The document where your product's promises are written. Whatever you call it, it is the file that says who this is for and what it promises them. You are going to collect on those promises line by line, so you need to know which line you are collecting.
2. The spec of every behavior the walkthrough will cross. A violated numbered rule is the strongest finding that exists, and without reading the spec you will not recognise one when you see it.

The persona is data, not prose

A persona is born in prose, because that is how you describe a human being. But before the app opens it becomes a file, in the vocabulary the product consumes. Full format in references/anatomy-of-a-persona.md, empty mould in templates/persona.json.

The four rules that give a persona fidelity:

Rule	Why
The level is output, never input	Declaring "she is a level 1 user" assumes what the product is supposed to discover. The persona declares what she lived through; the level is what the engine answers, and the engine is what is under test
Every persona declares at least one lived anchor, with the id of the question that measures it	The anchor is what turns "the funnel is short" into "the funnel never asked the one thing she actually lived through"
Experiment arms are declared, and the same persona runs in both	A different arm lights up a different bug. Without declaring them, two findings collapse into one and you cannot tell a screen defect from a calibration defect
Provenance is mandatory, and it limits what you may claim	simulated produces only findings about what broke, lied or blocked. interview and session may speak about desire and refusal

The protocol

1. Write or pick the persona, and derive the answer file before opening the app. Deriving it afterwards is writing the answer that justifies what you already saw.
2. Start the app from a clean profile, on a port of its own. Reusing a profile is the easiest way for the second walkthrough to measure the residue of the first.
3. Cross it answering what the persona would answer, without optimising, without going back to fix things, without using a shortcut she does not know.
4. Write every finding down as it happens, with the screen. A remembered finding is an edited finding.
5. Mark where she would have closed the app, and keep going anyway. That is what makes "blocks the journey" a measurement instead of an adjective.
6. Collect on the promises one by one, each with its source in file and line.
7. Check every line you cited before you close. A wrong citation in a report that demands precision costs the whole report its authority.
8. Generate the .html with the script. This is not optional.
9. Give a destination to every finding that blocks the journey.

Severity

Three rungs, and the criterion is what the person does, not how much it annoys you:

Rung	Means
blocks the journey	She cannot continue, or she continues without receiving what was promised
causes doubt	She continues, but starts to distrust the product or herself
annoys	She notices, dislikes it, and moves on

The shape of the report

Fixed. Empty mould in templates/report.md.

Opening: why this test, what it is not, the persona, and the verdict in one sentence. Then the numbered findings A1, A2, and each one carries:

• code and severity
• what happened, in the order it happened
• the cause, as file:line. A finding you cannot point at is not a finding
• the persona's words, in the first person
• the screen
• for the ones that block the journey, two more fields: the destination spec and the proposed surface tag

Then: the table of promises collected, what worked well (a report is long on problems and that unbalances the reading), and the repair order.

Two artifacts, always. The .md next to the screenshots, and the self contained .html produced by scripts/report-to-html.py. The HTML is the one somebody opens and understands without reading code, and it is what turns a finding into a decision instead of into a file.

Keep the whole thing out of any folder that is indexed and served back to users. A walkthrough report contains what a person answered, under a name. If your documentation folder feeds a retrieval index that answers user questions, a report living there is a privacy problem, not a noise problem.

The link to the gate

A finding that blocks the journey does not close as an issue. It closes as a rule.

It names the destination spec and the surface tag. Whoever fixes it writes the numbered rule and the numbered scenario carrying that tag, and from then on spec-coverage demands that a verifier exists and audit-tests demands that the verifier notices the break. Without that step the finding evaporates, and it can come back tomorrow without a single gate blinking.

Where the finding is a disagreement between two sides, it becomes a bilateral test: one table of cases that both sides load, never code written twice.

Excuses versus reality

Excuse	Reality
"I know what a beginner feels"	You are the bubble. That is the whole reason this exists
"the persona is obvious, I will write it later"	A persona written after the walkthrough is the one that justifies what you saw
"her level is 1"	That is the product's output. Declaring it as input kills the test
"the finding is clear, it does not need the line"	A finding without file:line is an opinion, and it disappears at the first disagreement
"I will generate the HTML later"	Later is never, and the .md alone does not become a decision
"I will open an issue and somebody will see it"	An issue does not fail a build
"it was simulated but you can tell she would not want it"	You cannot. Simulation does not measure desire, and claiming it contaminates what it does measure well
"the app has no handles, so I aim by text and move on"	Aiming by text is declared debt, not a solution. Record it

Red flags: stop and go back to the protocol

• You are writing the finding from memory, without the screen in front of you.
• You went back a screen to "do it right" before recording what went wrong.
• You used a shortcut the persona does not know (a direct URL, a keyboard shortcut the screen does not teach, an account already logged in) without declaring it in the report.
• The level showed up in the persona file.
• You are about to conclude something about wanting, paying or returning, and the provenance is simulated.
• You passed ten findings and none of them has a destination spec.

Quick reference

You want	Go to
Write the persona	references/anatomy-of-a-persona.md and templates/persona.json
Write the report	templates/report.md
Generate the HTML	python3 scripts/report-to-html.py <report.md>
Drive the app by command	node scripts/drive.mjs <port> <command>

Final checklist

• The persona is a file, with provenance and at least one anchor.
• The level does not appear as input.
• The arms are declared, and the walkthrough ran in both when the finding depended on it.
• Clean profile, thrown away at the end.
• Every finding has a screen and a cause as file:line.
• Every cited line was checked in the file.
• Every journey blocking finding has a destination spec and a surface tag.
• The promises were collected one by one, with sources.
• The .html was generated and opens with no network.
• The report lives outside any folder that is indexed and served to users.