🍪 TOUR-STANDARD.md: the review-tour standard

A diff describes an edit. A tour shows the thing. When a change is something a person can look at, the review should happen on the page, not in a patch, and the walk should be written by whoever just made the change while they still remember what to be nervous about.

This owns the artifact. LOOP.md section 4a owns the rule that a rendered change owes one, and section 2 owns the limit: a tour you wrote about your own change is not a second pass. Read them together, not instead of each other.

What a tour is

A markdown file in the host's tours folder, rendered by CRUMB. Frontmatter, an intro, then one ## <surface> heading per step. The surface is a data-surface address on the page, which is what the lamp lights.

---
id: review-live-figures
mode: dev
title: "Review: the figures went live"
route: /notes/ten-times-zero
---
The intro. What changed, in two or three sentences, and anything true of the whole change.

## figure:ratio
- at: /notes/ten-times-zero
- status: needs-verification
- review: What moved here, and why it is the risky one.
- verify: Scroll into it from the paragraph above. Nothing should overlap, at desktop and phone width.
The demo-mode narration. Shown in both modes; the review and verify lines are the dev half.

mode: dev is what makes it a review tour. Without it the review, verify and status lines still parse but the tour opens as a demo.

The seven rules

One step per surface that changed, not one per commit. The reviewer is checking the app, not your history. Two commits that both touched the same figure are one step. A commit that touched six figures is six.

A surface is anything a reader ends up looking at: a view template or the styles that dress it, a client script that drives one, a note body, a calendar post under content/events, and the JSON collections under content/data that a page reads straight through. Media is not on that list; a deck or a photograph earns a step through the post or the view that mounts it, never on its own. The list is written out because leaving it implied cost something real: the events collection arrived months after the checks that look for a rendered path, nobody widened them, and every calendar post in that window shipped without a tour while the loop reported nothing wrong. Any check that greps for a rendered path implements this list and does not get to hold its own private version of it.

The surface has to exist before the tour does. A step points at a data-surface address. If the thing you changed has no address, give it one first. That is usually a single attribute next to whatever hook the element already carries, and it is worth doing on its own: an addressable region is what makes anything, a tour or an agent, able to point at it later.

A verify line is an instruction, not a description. The test is whether someone who has never seen the code can follow it and end up knowing whether it worked. "Check the spacing" fails. "Scroll slowly into this figure from the paragraph above; nothing should overlap, at desktop width and at phone width" passes. Name the interaction, name the widths or states that matter, and say what the correct outcome looks like, especially when the correct outcome is that nothing happens.

A step is read standing up, so it is short. The card sits over the thing it points at, and the reviewer is looking past it at the app. A step that fills the card gets skimmed, and a skimmed step is worse than a missing one because it still looks like it was read. Two sentences for the review line and one instruction for the verify line is the size that gets used. The rule is not a word count so much as a test: if the card has to be scrolled, the step is doing something a step should not.

Long context is not banned, it is relocated, and the place is not another panel on the same screen. The reasoning behind a change, the history, the thing you nearly did instead: that is the plan and the run report, which a reviewer reads when they want it and skips when they do not. A review chrome that mirrors the step's prose beside the card has not solved anything, it has printed it twice, and the second copy is the one nobody reads. If a step will not fit its card, shorten the step.

Stamp the status honestly, and use needs-verification more than feels comfortable. The five are new, changed, needs-verification, verified, known-issue. verified means someone who did not write it has actually walked it. Marking your own work verified is the exact move the standard above refuses, so on a tour you wrote about your own change, verified is almost always wrong. known-issue is not an admission of failure, it is the cheapest way to stop a reviewer filing something you already know about.

A step that stages state says so, in its own prose. A tour may write into the app, through the app's own door, and a prefill line is the first thing that does it. The moment it does, the screen the reviewer is looking at is no longer one the app reached by itself, and a screen with words already in it reads exactly like one that did. So the step says plainly that the tour put them there, and what the tour then refused to do (the message is staged, sending it is yours). The client draws a staged label of its own, which is a label, and labels get skipped. Saying it in the narration is the part someone actually reads, and a review tour that lets a staged state pass for a real one has inverted the only thing it is for.

Say what is riskiest, not what is most impressive. The step most worth a careful look is usually the smallest one: the spacing fix landed at the end, the edge case nobody asked for. Put the honest nervousness in the review line. A tour that reads like a changelog of wins is hiding the same thing a run report full of wins is hiding.

The handoff

A review tour is written for one change and handed to one person, so the handoff is a link. Any URL on the host takes the tour id as a query parameter, plus the mode and the framed presentation:

https://example.com/notes/my-post?crumb=review-my-change&crumb-mode=dev&crumb-frame

End the run report with that link. A tour nobody was handed is a file, not a review.

Close the loop in the tour, not in chat. A tour may end with a ## prompt section: the questions the walk could not answer itself, and a template that composes the answers into a prompt to paste back into a session. Use it for the judgements only the reviewer can make (does this read right, which piece comes next), never for something the walk already showed. Two or three questions is the size that gets answered; a form of eight is a survey, and a survey gets closed. The grammar is in WRITE-A-TOUR.

Where it lives, and who sees it

Flat, in the host's tours folder, named review-<slug>.md. Not in a subfolder: the loader reads the folder without recursing, so a tour one level down is invisible to the board and fails silently, which is the worst of both.

Check whether the host publishes its tours before writing anything you would not put on the live site. On tjakoen.github.io the tours folder is exported, so a review tour ships publicly, and that is deliberate: it is a receipt. On a host where that is not wanted, the folder has to move out of the exported tree first.

Rationalizations

Red flags

• A verify line that starts with "Check" or "Make sure" and names no interaction.
• Every step stamped changed, with no sense of which one to look at first.
• A step whose review line restates the commit message.
• A tour whose steps outnumber the surfaces that actually changed.
• A tour written but never linked in the run report.

Verification

• [ ] Every changed rendered surface has exactly one step, and no step points at an unchanged one.
• [ ] Every step's surface address resolves on the page the step names.
• [ ] Every verify line names an interaction and the outcome that means it worked.
• [ ] No step the author wrote about their own change is stamped verified.
• [ ] crumb check passes on the tours folder.
• [ ] The handoff link is in the run report.

🤖 Built with Claude, and the tour is how I make it check the work rather than take my word for it. I decided what "reviewed" has to mean; Claude typed the parser that enforces it. I don't prompt and pray, I prompt and prove. How I actually work with AI, receipts and all →