flow-walkthrough
Flow Walkthrough Skill
Task lists, compilers, and code review verify that screens exist and compile. They are structurally blind to whether the flow between screens actually works for a human with a goal — the transitions, the return paths, the dead-ends, the discoverability. This skill closes that gap.
Why this exists (the three failure classes)
Real UX bugs fail at three different layers, and no single mechanism catches all three — so this skill uses three:
| Failure class | Example | Caught by |
|---|---|---|
| Dead-end / missing path | A saved record can only be viewed, never reopened to edit; Done calls popToRoot() and orphans an in-progress entity |
Layer 1 — static nav-graph audit (no build) |
| Reachability regression | "Run round" no longer reaches the capture screen after a refactor; a Done lands on the wrong screen |
Layer 2 — automated flow driving (XCUITest) |
| Discoverability | "How do I even select a contestant?" — the only affordance is a bare row tap | Layer 3 — human checklist (a UI test taps the row and passes) |
The trap: a UI test happily taps a hidden control and reports PASS. Automation proves a path works; only a human judges whether it is findable. That residue is why Layer 3 is mandatory, not optional.
Input: the <flows> from PLAN.md
/apple:plan emits a <flows> block — end-to-end journeys, each a testable script. If PLAN.md has no <flows>, derive them from the phase's <mvp-features>/views and write them back into PLAN.md first (a flow that isn't written down can't be checked). A good flow names, for every persisted entity created: the step that reopens it editable, and the single least-discoverable action.