Write Flow Guide

Write Flow Guide

A product walk is a human driving the real app through every user-facing ability and judging what they see. The deliverable is a run file, a rendered human guide, and a vet-flow-guide report — grounded in the app's own rendering, one row per ability case, each tagged with the requirement ID and a case kind. Cases and verdicts live in the same file, so what the agent proves is what the person reads. Build the artifacts; a chat message is not the deliverable. A guide of only happy paths is not done. Authoring is not complete until the vet report exists.

Case taxonomy (every guide uses these kinds)

Do not invent chaos, load, race, or security-fuzz suites here — those are not a one-seat user pass. Permission/role cases belong when the UI exposes them (edge or error + setup for the role).

Todos — GATE

Before §1, put one item per section (1–4) on a visible list — the harness's todo / task-list tool when it exposes one, otherwise a checklist written into your reply and restated at each section boundary — and one terminal todo Vet flow guide (vet-flow-guide on the run file — created now, not later). Check the vet todo off only when .skills/<CODE>/vet-flow-guide.md exists for this run file. Done when: the list exists before scoping and includes the vet todo.

1. Scope every ability — coverage gate

Read the feature's requirements.md, design.md, tasks.md. List every user-observable ability. Include adjacent capabilities in the same user workflow, not only the new feature.

Coverage rules (all must hold before §4 is done):

1. Every user-facing requirement ID has ≥1 case.
2. Every ability area (section of the guide) has ≥1 happy and ≥1 non-happy among edge | error | nonbehavior | persist.
3. Every Out-of-Scope / deliberate non-behavior that a user could try has a nonbehavior case (or an explicit note in the hand-off: no user-facing way to attempt this — skipped).
4. Every criterion that claims persistence has a persist case (or a happy/edge whose Expect + backend prove reload/store — prefer a dedicated persist row so it cannot be skipped).
5. If the area has no edge, error, nonbehavior, or persist material in the spec, write one line under that section: Coverage exception: no edge/error/ nonbehavior/persist cited in spec — do not invent product behavior. The exception is greppable honesty, not a free pass when the triad has edges.

One happy case per ID is not enough when the ID or its siblings name edges.

Done when: the coverage rules above hold, or every exception is written on the guide.

2. Ground each case in the real code

For each case, read the code to get what the user will ACTUALLY see: the exact vocabulary (keywords, command names, labels), keyboard shortcuts, and the real rendering — badge colors, chip styles, icons — pulled from the source (theme tokens, CSS), never guessed. Where the code reveals an honest caveat (a delimiter dimmed not removed, a status with no UI yet), the case says so.

3. Boot the real app and find the honest observation point

Start the app with the Run locally (dev) command from docs/agents/project.md (discover and record it if missing — see validate-ui). Surface any degraded area up front: a feature needing a key, a sub-feature not built yet. A behavior with no UI surface still gets a case — with a real way to observe it (a devtools invoke(...), a read-only DB peek), never a pretend screen. Done when: the app is running and every not-yet-visible behavior has an observation method.

4. Write cases + render the shell (do not invent CSS)

Authoring SSOT is the run file, not hand-rolled HTML.

1. Write .skills/<CODE>/flow-guide.json (schema: load sibling references/cases-schema.md when unsure). Every case carries all required slots: id, req, kind, title, setup, try, expect, backend (backend is the server-side assertion, or the literal presentational). Run state (run, human) is filled in for you — author the eight slots.

2. Render the human guide from the checked-in shell — do not load craft-page or invent a palette/layout unless the user explicitly asks for custom craft:

   python3 <skill-root>/scripts/flow-guide render .skills/<CODE>/flow-guide.json \
     -o .skills/<CODE>/flow-guide.html
   

   Resolve <skill-root> to this skill's install path (in this monorepo: skills/acceptance/write-flow-guide). The shell is shell/guide.html — theme-aware CSS/JS, kind chips, verdict badges, and data-* attributes. The rendered page carries the verdicts as of render time and says so, so it is correct on a double-click with nothing running.

3. Coverage self-check: count cases by kind per section. If any ability area lacks a non-happy kind and has no Coverage exception line, add the missing cases before hand-off.

Optional: at most two journey rows; they do not replace atomic coverage.

Never ship a chat-only checklist. Never regenerate a full custom HTML page as the default path — cases + render is the path.

Done when: the run file and rendered HTML are on disk at known paths, coverage holds, every case has all required slots.

5. Hand over

Order: artifacts → run vet → optional serve → dogfood only after clean vet.

1. Artifacts — give both paths (run file + HTML), the fastest way in — a ~30-second first pass that lights the feature up (usually the first happy row) — then degraded-feature notes and coverage exceptions.

2. Vet IMMEDIATELY. After the run file and rendered HTML are on disk and §4 coverage holds, IMMEDIATELY REQUIRED SUB-SKILL: use vet-flow-guide on the run file — before serve, dogfood, or any “authoring done” claim. Mark the Vet flow guide todo done only when .skills/<CODE>/vet-flow-guide.md exists. §1 / §4 coverage self-check is authoring hygiene, not a substitute for this report.

3. Optional serve — offer the live guide when they will be testing by hand alongside the agent:

   python3 <skill-root>/scripts/flow-guide serve .skills/<CODE>/flow-guide.json
   

   It binds 127.0.0.1:8787, follows verdicts as the agent records them, and writes their ticks back where the agent can see them. Tell them plainly what a tick means: it records that they looked, and never becomes a pass. Stopping it is serve --stop. Opened as a plain file instead, the guide still shows the verdicts it was rendered with — the server only buys freshness.

4. Agent dogfood — run it. After a clean vet-flow-guide report (or a named override on open findings), REQUIRED SUB-SKILL: use run-flow-guide on this run file. Before the report exists, do not name it at all.

   The hand-off is a route, not a gate: a control measured on 2026-09-09 drove the app unprompted rather than stopping at the artifact it had just written, so nothing here needs to argue it into verifying. What it does need is the address — verification done ad hoc produces no run file, no per-case verdicts, and no server probes, so downstream has nothing to read.

   Ends here instead when the user asked for a hand walk: step 3's serve is the deliverable and their ticks are the record.

Done when: artifacts are on disk, grounded, the §1 coverage gate holds, every case is fully slotted, .skills/<CODE>/vet-flow-guide.md exists for this run file, and the guide has been handed to run-flow-guide — or a hand walk is recorded as the user's explicit choice.

Rationalizations

Red Flags

• Hand-writing a full HTML/CSS page instead of the run file + flow-guide render
• Missing backend / setup / kind on any case
• Happy-only section without a greppable coverage exception
• Telling the agent to mark progress via guide ticks instead of write-flow-guide mark
• Treating §4 coverage self-check as a substitute for vet-flow-guide
• Declaring this skill done without .skills/<CODE>/vet-flow-guide.md for this run file
• Naming run-flow-guide (or offering dogfood) before a vet report exists
• Verifying the feature ad hoc instead of through run-flow-guide, leaving no run file
• Checking off the Vet flow guide todo when the report path does not exist