Flow Walkthrough Skill

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:

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.

The method

Layer 1 — Static navigation-graph audit (no build required)

Grep the navigation surface and reason over it. Do this first; it's free and catches the highest-severity class.

1. Build the graph. Find entry points and edges:
   • Grep: NavigationStack, navigationDestination, NavigationLink, \.sheet, \.fullScreenCover, router.push, enum Route, dismiss(), popToRoot, @Query.
2. Assert reachability & return paths. For every screen: how do you get in, and does every Done/Back/dismiss land somewhere intentional? Flag any popToRoot() that discards an in-progress or just-saved entity.
3. CRUD-completeness. For every @Model with a Create path, is there a Read and an Update/reopen path from the persistence surface (a list/history)? A list that only opens a read-only detail is a dead-end for editing — flag it.
4. Entry-point sanity. Does "New X" always create a fresh entity with no way back to the previous one except an incomplete list? Flag create-only loops.
5. Nested navigation containers. For every NavigationLink/navigationDestination destination, check whether the destination view declares its own NavigationView/NavigationStack — a pushed view must never wrap one. This renders a second nav bar under the parent's and its leading bar items displace the back button. It's a cross-file bug: each file looks correct alone (and previews fine in isolation), so single-file review never catches it — only this pairwise check does.

Output each finding as DEAD-END / NO-EDIT-PATH / ORPHANS-ENTITY / NESTED-NAV with the file:line and the missing arrow.

Layer 2 — Automated flow driving (XCUITest + per-step screenshots)

Turn each <flow> into a UI test that taps through it and screenshots every step, so the agent can see the transitions and assert the destinations.

1. Ensure a UITest target exists. If none, add one (xcodegen: a type: bundle.ui-testing target; or xcodebuild). Keep the generated tests — they become the Phase 5 regression suite.