Flow Walkthrough

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.
2. Generate one test method per flow from <steps>. After each step, attach a screenshot:

   func snap(_ name: String) {
       let s = XCTAttachment(screenshot: XCUIScreen.main.screenshot())
       s.name = name; s.lifetime = .keepAlways; add(s)
   }

   Launch with any needed args (e.g. a -uiTestSeed launch argument that seeds SwiftData and, in DEBUG, flips entitlement flags so gated flows are reachable without a real purchase). Assert the destination of each step (XCTAssert(app.staticTexts["Results"].waitForExistence(timeout: 2))), especially after Done/Back — that is what catches wrong-destination bugs.
3. Run and extract:

   xcodebuild test -project <App>.xcodeproj -scheme <App> \
     -destination 'platform=iOS Simulator,name=<device>' \
     -resultBundlePath .planning/walkthrough/<flowId>.xcresult
   # export per-step screenshots for the agent to read:
   xcrun xcresulttool export attachments \
     --path .planning/walkthrough/<flowId>.xcresult \
     --output-path .planning/walkthrough/<flowId>/   # adapt flag to installed Xcode

   (The xcresulttool attachment-export subcommand name shifts across Xcode versions — check xcrun xcresulttool --help and adapt.)
4. Read the screenshots in order → a "filmstrip." Confirm each step lands where the flow says it should. A failed assertion or a wrong screen = a flow bug with visual proof.
5. One unseeded pass (fresh-install reality). Every seeded run hides zero states — run at least one pass with NO seed argument that visits each top-level screen and screenshots it, in light mode. Assert each zero state renders something intentional (an empty-state view, a hint), not a blank expanse. A user's first launch is unseeded; if every automated capture is seeded, blank first-run screens ship unseen.

Layer 3 — Human discoverability pass (the irreducible residue)

For each flow, emit a short script the human runs and rates — this is the only thing that catches "I couldn't find how to do X":

Flow F1 — Run a contest (as a host)
  1. Tap "Start a Contest"        → were you sure what to tap? (1–5)
  2. Add two contestants          → was adding the *second* obvious? (1–5)
  3. Run each contestant's round  → did you know rows were tappable? (1–5)
  4. Done on results              → did you land back where you expected? (Y/N)
  Where did you hesitate? ______

Keep it to the 2–4 flows that matter; ask for a hesitation note, not just scores — the note is where the real bug hides.

Output: .planning/WALKTHROUGH.md

# Flow Walkthrough — Phase [N]

## Layer 1 — Navigation graph (static)
- 🔴 NO-EDIT-PATH: ContestHistoryView:19 opens read-only ResultsView; a saved Contest can't be reopened to edit. → route to editable setup.
- 🔴 ORPHANS-ENTITY: ResultsView "Done" calls router.popToRoot() → dumps user home, loses the contest. → dismiss() one level.

## Layer 2 — Driven flows (filmstrips in ./walkthrough/)
| Flow | Result | Note |
|------|--------|------|
| F1 create→run→results→reopen | ❌ DEAD-END at step 6 | reopen lands on read-only results |
| F2 add second contestant | ✅ reaches capture | |

## Layer 3 — Human discoverability checklist
[the per-flow scripts above, for the user to fill in]

## Verdict
[N] dead-ends (fix before phase-complete), [N] reachability failures, discoverability pending human pass.

Store screenshots under .planning/walkthrough/<flowId>/. Fix all Layer-1 dead-ends and Layer-2 failures before the phase is marked complete (same gate discipline as visual-qa).

Honest limits

• Tests can't judge feel or findability. A green Layer-2 run with an unrated Layer-3 checklist is not a pass.
• Seeding is required for gated/late-state flows. Provide a DEBUG -uiTestSeed path (insert sample models, set entitlement flags) so reopen/edit/results flows are reachable without manually rebuilding state each run. Remove or guard it behind the launch arg so it never affects release.
• Discoverability findings are design changes, not bugs to "fix in code" blindly — surface them, let the human decide.

Cadence & integration

• Run per flow-slice, not per-phase. Right after you build the create→edit→results loop, walk that loop — don't wait for the whole phase. Bugs are cheapest the minute they're introduced.
• Complements, doesn't replace, visual-qa (which is static/code-level: colors, touch targets, view states). This skill is about flow, that one is about screens.
• Feeds Phase 5. The generated XCUITests are kept as the regression suite; hand them to testing/tdd-feature/test-spec rather than re-writing.
• Pairs with a nav-graph review lens. If /apple:review gains a flow/dead-end agent, Layer 1 can run there too; this skill is the runnable, screenshot-producing counterpart.