Journey Qa

Journey QA

Green CI proves the OLD surface's tests still pass; it says nothing about whether a NEW shell's user journeys make sense. Two TestFlight builds shipped "non-sensible" UIs through fully green gates because nobody walked the journeys. The fix: a machine-readable journey map grounded in code evidence, a generated human test guide, and binding rules. This skill owns "does it work end to end"; [[design-fidelity-loop]] owns how it gets beautiful; [[honest-verdicts]] owns what counts as evidence; [[resilient-agent-lanes]] owns how the resulting fix lanes run.

When to invoke

• Starting any new UI program (new shell, redesign, rebuild).
• Before ANY external distribution (TestFlight, beta, release).
• After a founder/user report of "it doesn't make sense" / "taps go nowhere".
• At feature-flag flips that swap which shell/screens are live.
• When a PR claims to fix or advance a user-facing flow.

1. The journey map (machine-readable YAML)

One file, e.g. docs/journeys/-journeys.yaml (or docs/design//journeys.yaml when /ux-design authored it — that skill designs the journeys this skill verifies; same schema, same ids). Schema per journey:

- id: J2                      # stable id, referenced by PRs and lanes
  name: Daily loop (next action -> start)
  uc: [UC-002]                # use-case refs
  entry: {app_state: ..., action: ...}
  steps:
    - surface: NOW (Z0)       # screen/overlay the user is on
      action: tap Start
      expect: focus overlay opens for THAT task
      axid: e17.startButton   # accessibility id when one exists
      status: PARTIAL         # WORKS | PARTIAL | STUB | MISSING | UNKNOWN
      evidence: "SceneViews.swift:29-30 (why, with the gap named)"
      owner_lane: E19-G3      # or NO-LANE (see section 4)
  exit: returns to NOW

A meta: header pins branch, commit, and audit date -- statuses are claims about a SPECIFIC commit, never about "the app".

Status rules (non-negotiable):

• Statuses come ONLY from reading the live code path or observing on device.

Never from PR descriptions, lane reports, or test names ([[honest-verdicts]]: a claim without executed evidence is not evidence).

• Evidence is file:line on the audited commit, plus the gap named in words.
• WORKS means: failing this step on device is a NEW bug. If you would hedge

that sentence, it is PARTIAL or UNKNOWN.

• Code that exists but is unmounted/unreachable from the live entry point is

MISSING, not WORKS. Grep for references from the composition root.

2. The human test guide (generated, never hand-forked)

Generate -TEST-GUIDE.md from the YAML. Conventions:

• [ ] checkbox per step; unmarked = should work, failure = new bug.
• !! marks known gaps (PARTIAL/STUB/MISSING) with a one-liner of what the

tester will see and which lane owns it -- so a failing !! step is confirmation, not a bug report.

• State how to ENTER the flow and any known exit traps up front.

Regenerate the guide whenever the YAML changes; drift between them is a bug.

3. Enforcement rules

• Every UI PR names the journey ids it advances AND updates the status +

evidence of every step it changes, in the same PR. No journey id = the PR must explain why it touches no journey (rare; usually means a missing journey -- add it).

• New screen or flow with no journey covering it: block until a journey is

added. Unmapped surface is unaudited surface.

• Re-validate the map (fresh code read of changed journeys, bump meta commit)

after every merge wave and before ANY distribution. A map audited at commit N is stale evidence at commit N+20.

• Device-walk gate: before external distribution, a human (or driven device

run) walks the guide ON DEVICE -- not simulator-only -- with per-step screenshot evidence for the core set. Simulator passes do not clear this gate (fresh-environment rules per [[honest-verdicts]]).

• Core-journey blocklist: name the core set (e.g. "J2/J3/J4") and hold

distribution until they pass on device. Write the hold where the release process will see it (roadmap/memory), not only in chat.

• Flag flips: journeys that exist only in the legacy surface move to an

explicit "orphan appendix" in the YAML -- they are consciously retired or re-homed, never silently lost.

4. Deriving work from the map

• Every non-WORKS step gets an owner_lane pointing at a real fix lane, with

the evidence pointer carried into the lane brief (the example-app G11 pattern: gap -> lane, evidence pre-located, no re-discovery cost).

• NO-LANE is allowed in the map but is a standing red flag: after every

audit, list all NO-LANE steps and put them in front of the lead. A gap nobody owns is how "non-sensible" ships again.

• Lanes run per [[resilient-agent-lanes]]; on lane merge, the lane's exit

criterion includes flipping its journey steps' statuses with new evidence.

Failure modes this exists to catch

• Map drift: statuses audited at an old commit treated as current.
• Aspirational WORKS: status set from intent or a PR claim, not code/device.
• PRs name journey ids they don't actually advance (verify the diff touches

the evidence path).

• "Works on simulator": device gate exists because it has diverged.
• New screens landing with no journey; gaps landing with no lane.
• Guide forked by hand and drifting from the YAML.
• Legacy journeys vanishing unexamined at a flag flip.

Worked example (example-app Glow)

docs/journeys/glow-journeys.yaml (J1-J11, audited at origin/main 8166044) + GLOW-TEST-GUIDE.md with !! gap markers; every Glow UI PR names journey ids; TestFlight distribution held until J2/J3/J4 pass on device; non-WORKS steps became the E19 G11 lanes, NO-LANE steps escalated to the lead.

Time-based UI: assert progression, not presence (2026-07-20)

The focus timer shipped frozen at 00:00 through every build because its tests asserted the timer ELEMENT existed, never that its VALUE changed. For any time-based or animated surface (timers, progress rings, streaks counting up), a WORKS claim requires an assertion that the displayed value progresses across a captured interval (two reads, different values), not just that the element renders. Presence-only tests on dynamic UI are vacuous.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dndungu
• Source: dndungu/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.