Lists and pages that stay true
Journeys as typed data, prose generated
The few paths that matter through a product, declared in code against the events the system already records, with the written version generated from them.
One of 15 patterns I've found working with AI coding agents. An agent drafted the words from my notes, and I haven't edited them yet. See all 15, or read how they are made.
An agent drafted the words from my notes, and I haven't edited them yet. The code was run before it went in.
The problem
A product has a few paths that matter: sign up, create something, finish the task, read the result. Someone wants them written down so a person who does not read code can see what the system does.
The usual places are a diagram in a whiteboard tool, or a scenario file, the steps written in plain English for a test runner to match against code. The diagram is edited by hand while the code changes daily, and nothing connects the two. The scenario sentence can stay true-sounding while the code underneath it moves. And a reader who does not read code has no way to catch a false map, which makes a wrong map worse than none.
The idea
Declare each journey in code. A journey is a name, an actor and an ordered list of milestones, and each milestone names an event, a named entry the system already writes when something happens, from a list the type checker knows. The type checker is the tool that rejects a name that does not exist. Rename an event and the journey stops compiling.
Everything in English is generated from the declaration: a short document per journey, committed and checked against a fresh render. A test walks a recorded list of events and passes when the milestones appear in order. Every event is either on a journey or on a short list that says why not, and the length of that list is fixed at a number in the test, so adding to it is a visible change.
A version small enough to read
Eight event names, two journeys, one built on the other, and a list of the three events on no journey.
// Journeys declared against the event names the system already records.// Run: bun journeys.ts. Type-check: tsc --noEmit --strict --target es2022 --lib es2022,dom journeys.tsconst EVENTS = ["account.created", "email.verified", "project.created", "invite.sent", "report.generated", "report.viewed", "comment.saved", "theme.changed"] as const;type EventName = (typeof EVENTS)[number];
type Journey = { name: string; actor: string; steps: { event: EventName; says: string }[] };
const signUp: Journey = { name: "sign-up", actor: "a new user", steps: [ { event: "account.created", says: "creates an account" }, { event: "email.verified", says: "confirms their email address" },] };const firstReport: Journey = { name: "first-report", actor: "a new user", steps: [ ...signUp.steps, { event: "project.created", says: "starts a project" }, { event: "report.generated", says: "runs their first report" }, { event: "report.viewed", says: "reads the result" },] };const journeys = [signUp, firstReport];
// Events on no journey, each with a reason. The length is pinned below.const offJourney: Partial<Record<EventName, string>> = { "invite.sent": "Optional: most people never invite anyone.", "comment.saved": "Optional, so not a step anyone can drop out of.", "theme.changed": "A setting, not progress.",};const OFF_JOURNEY_PIN = 3;
// Pass if the steps appear in order; other events may come between them.function walk(j: Journey, recorded: EventName[]): string { let i = 0; for (const e of recorded) if (e === j.steps[i]?.event) i++; return i === j.steps.length ? "finished" : `stopped before "${j.steps[i].event}" (step ${i + 1} of ${j.steps.length})`;}
const prose = (j: Journey) => `# ${j.name}\n\n` + j.steps.map((s, n) => `${n + 1}. ${j.actor[0].toUpperCase() + j.actor.slice(1)} ${s.says}.`).join("\n");
const problems: string[] = [];const onAJourney = new Set(journeys.flatMap((j) => j.steps.map((s) => s.event)));for (const e of EVENTS) { if (!onAJourney.has(e) && !offJourney[e]) problems.push(`${e} is on no journey and not on the off-journey list.`); if (onAJourney.has(e) && offJourney[e]) problems.push(`${e} is now on a journey. Delete it from the off-journey list.`);}if (Object.keys(offJourney).length !== OFF_JOURNEY_PIN) problems.push(`The off-journey list has ${Object.keys(offJourney).length} entries; its pin is ${OFF_JOURNEY_PIN}.`);
console.log(problems.length ? problems.join("\n") : "coverage ok");console.log(`\n${prose(firstReport)}\n`);const run: EventName[] = ["account.created", "theme.changed", "email.verified", "project.created", "report.generated", "report.viewed"];console.log(`A full run: ${walk(firstReport, run)}`);console.log(`A run that never read: ${walk(firstReport, run.slice(0, 5))}`);
// The lesson: put an optional act on a journey and a finished run fails.const withComment: Journey = { ...firstReport, steps: [...firstReport.steps.slice(0, 4), { event: "comment.saved", says: "leaves a comment" }, firstReport.steps[4]] };console.log(`With an optional step: ${walk(withComment, run)}`);Run with Bun, a JavaScript runtime, it prints:
coverage ok
# first-report
1. A new user creates an account.2. A new user confirms their email address.3. A new user starts a project.4. A new user runs their first report.5. A new user reads the result.
A full run: finishedA run that never read: stopped before "report.viewed" (step 5 of 5)With an optional step: stopped before "comment.saved" (step 5 of 6)Rename report.viewed to report.opened in the list of events, and the type check fails. Its errors include Type '"report.viewed"' is not assignable to type, followed by the list of real event names.
The last line is the one I'd take away. Leaving a comment is optional. Put it on the journey, and a person who finished everything that mattered is counted as having stopped.
Where the plain form falls short
The plain form is a diagram, or a typed journey with no test of what counts as a step. I've met each of these.
- An optional act is made a step. One journey had saving a comment in the middle. The end-to-end test then had to post a comment no real user needs to post, only to pass, and that was the sign the step was wrong. The test I use now: has a person who skips this failed at anything?
- A step happens on one route only. People who finished by the other route were counted as having dropped out.
- A step records nothing. If the system writes no event for a milestone, the journey cannot be checked there. It can stay on the map as explanation, but the walk skips it, and it is worth saying so.
- The generated page drifts anyway. If the comparison runs inside a test step whose earlier result is saved and replayed, a change that only edits the document replays the old pass. Run it outside the cache.
- Excusing an event is one quiet line. Pinning the length of the off-journey list makes each new excuse a visible change someone has to agree to.
Trade-offs
- The walk proves order, not count. It cannot tell a step done once from one done nine times.
- The off-journey list tends to grow. In each place I've used this, it is longer now than when it started. The pin made the growth visible and reviewed. It did not stop it.
- The reasons are read, not tested. A reason such as "no code writes this event" still passes after someone adds code that writes it.
- Coverage stays small. A handful of journeys is normal. They are for the paths that matter, not every behaviour.
When to use it, and when not to
It suits a product that already records named events, has a few paths people care about, and has readers who need to see those paths without reading code. Without a fixed list of events the steps have no list to be typed against, and the map is a diagram again.
Example. Typed journeys, on GitHub
A draft skill for this pattern
A skill is a short set of instructions you give a coding agent so it applies a pattern the way you would. Copy the text below into a file called SKILL.md, in the folder your coding agent reads skills from. In Claude Code, Anthropic's coding agent, that is .claude/skills/typed-journeys/. It is a draft, and I haven't tried it on anyone else's project yet.
---name: typed-journeysdescription: Use when a product's main user paths are kept as a diagram or scenario file that has drifted from the code, or when someone asks for documentation of what the system does for a person who does not read code. Declares each journey in code against the real event names and generates the prose.---
# Typed journeys
A journey is a short ordered list of milestones from one person's point ofview: sign up, create something, finish the task, read the result. Declare itin code, typed against the events the system already records, and generateeverything written in English from it.
## Before you start
The system needs a fixed list of event names in code. If a milestone recordsnothing, it can stay on the map as explanation, but the test will skip it.
## Build it
1. A journey is a constant: name, actor, and steps. Each step names an event from the existing typed list, so renaming the event fails the type check.2. A step is something everyone on the path does. Ask: has a person who skips this failed at anything? If not, it is optional and does not belong on the journey, or everyone who skips it is counted as a drop-out.3. A walk function: given a recorded list of events, pass when the steps appear in order. Other events may come between them.4. A generator writes one document per journey. Commit it and fail when the committed text differs from a fresh render. Run that comparison outside any cached test task, or a change that only edits the document replays an old pass.5. Every event is on a journey or on an "off-journey" list with a one-line reason. Fail an event on neither, and an event on both. Pin the length of the off-journey list in the test, so adding an excuse is a visible change.
## Prove it can fail
Rename an event, add an event to no journey, put a listed event on ajourney, and hand-edit a generated document. Each should fail with its ownmessage. Then add an optional step and watch a finished run fail.
## What it does not do
The walk proves order, not count: it cannot tell once from nine times. Thereasons on the off-journey list are read by people, not tested, and the listtends to grow. The pin makes the growth visible; it does not stop it.