Journey Walkthroughs
On this page
Human-followable, click-by-click scripts that mirror the automated
journey-* E2E specs — the "human-fidelity" half of epic &61. Each
walkthrough tells a tester which persona to log in as and, for every step,
exactly what to type and click, with the expected screen state and a
spec-generated screenshot.
Driving a live demo? Every shipped journey below is now dual-persona and live-verified (#991): an applicant files through the real applicant portal front door, a caseworker records the facts + acts, and (where the case is portal-filed) the applicant signs back in to view the outcome. Each walkthrough carries a reproducibility tier (Fully manual / Worker-driven / Harness) and a concrete applicant precondition. For one-time bring-up, the reset between journeys, and the per-journey starting points, see the Demo Runbook.
The pairing rule (machine-enforced)
Every covered journey scenario in compliance/scenario-inventory/*.toml
must ship both artifacts:
-
the automated
journey-*.spec.tsPlaywright spec (thee2e-specbinding), and -
a human-followable walkthrough on this site (a
walkthroughbinding to an.adocunder this module).
cargo xtask scenarios audit enforces it (ADR-031 §3 amendment): a covered
journey with neither a walkthrough binding nor an issue-backed
walkthrough_blocked_by fails the gate (MISSING-WALKTHROUGH), a
walkthrough that doesn’t name its scenario or references an uncommitted
screenshot fails (DANGLING), and any journey-*.spec.ts that no binding
references fails (ORPHAN-SPEC). Personas come from
the applicant seed cast
(HH-ca5700xx) and the worker Keycloak user jane.caseworker / password.
Status
Shipped walkthroughs
-
SNAP intake → determination → Notice of Action —
snap.intake.thirty-day-determination-noa(#850). The intake-to-notice arc is fully hand-followable (portal apply → worker determination → NOA), so it ships a real, screenshot-verified walkthrough. -
SNAP substantial lottery/gambling winnings → adverse action —
snap.change.substantial-lottery-winnings(#973). The worker opens the certification (the new Create-certification action), records the winnings on the Income tab, re-determines to a denial, and confirms the adverse-action notice. -
SNAP mid-certification material income change → recert nudge → notice —
snap.change.income-exceeds-130pct-mid-period(#973). The worker opens the certification, records a material income increase on the Income tab, files the recert from the materiality nudge on the Renewals tab, and confirms the change-in-circumstances notice. -
SNAP address change → shelter-cost cascade → benefit recompute —
snap.change.address-change-shelter-cascade(#973, #983). The worker opens the certification, runs a baseline determination, records the move through the Address tab editor (#983), records the higher rent on the Expenses tab (the move’s separate shelter-cost consequence), re-determines to a higher benefit, and confirms the notice. -
SNAP change of circumstances during a pending fair hearing —
snap.hearings.change-during-pending-hearing(#974). The worker files a fair hearing (the new File-appeal action, continued benefits granted), acts on an unrelated shelter change, files a second hearing on the new action, and confirms the original hearing stays pending. -
SNAP approval + family consent grants the children Medicaid (Express Lane) —
xp.ele.partner-approval-grants-medicaid(#977). The worker records the family’s ELE consent (the new Record-ELE-consent action); that consent drains the household’s deferred SNAP approval and grants each eligible child a Medicaid-tier flag, which surfaces on the case identity hero. The applicant can also self-consent on the apply wizard’s income step. -
A change reported through the TANF case counts as a SNAP report —
snap.change.pa-household-cross-program-report(#978). The worker files the household’s second program (TANF) through the new File-application action, records one income change on the Income tab, and re-runs each program — both SNAP and TANF flip approved → denied on the single shared-fact change. -
A lapsed SNAP certification churns back through reapplication —
snap.certification.closure-churn-reapply(#979). The worker backdates a certification through the Create-certification form to lapse the case (backdating made human-followable), files a reapplication through the File-application action, re-determines, and recertifies forward — the household’s in-force coverage transitions from lapsed (end < today) back to covered (end ≥ today). -
A retroactive income correction recomputes a SNAP overpayment —
snap.integrity.claim-calculation-lookback(#976). The worker opens an enrollment and issues three past benefit months through the new Create-enrollment / Issue-benefits actions (the prior issuances the claim looks back on), authors a retroactive over-income correction on the Income tab, and recomputes the overpayment through the existing Recompute-overpayment action — an overpayment claim opens and its notice surfaces on the Notices tab. -
An upheld SNAP hearing turns continued benefits into an overpayment —
snap.hearings.upheld-decision-claims-continued-benefits(#975). The worker opens an enrollment and issues the continued-benefits months, files a backdated, timely appeal through the File-appeal action (the new Date-filed field grants continued benefits), and records the Upheld decision through the new Record-decision action on the Appeals tab — the appeal reads back decided with the assessed overpayment, and a claim auto-opens in the SNAP ledger. -
A TANF case closing for employment freezes SNAP into a transitional certification —
snap.certification.transitional-benefits-on-tanf-closure(#980). The worker files + approves TANF, records new earnings on the Income tab, and re-runs the TANF determination (now denied for earned income → the case closes) — the frozen five-month transitional SNAP certification then displays on the SNAP Determination tab (frozen allotment, closure reason, reporting waived), gated to SNAP-scoped workers. -
The 3730 periodic-report calendar closes a nonfiling case —
snap.change.periodic-report-nonfiler-termination(#1109, #1135). Clock-driven: the worker creates the cohort certification + enrollment, then the calendar runs itself under advancing logical clocks — the 15th-of-prior informational letter, the 5th-of-due combined reminder/termination letter (which IS the final notice) minting the adequate-notice-exempt action, and the month-end enact sweep closing the case.
Blocked walkthroughs. None — every covered SNAP journey scenario in
compliance/scenario-inventory/*.toml now ships a paired walkthrough. When a
future covered journey outpaces its worker/applicant-portal UI, mark it
walkthrough_blocked_by its UI-gap issue(s) rather than shipping a fig-leaf
stand-in; the walkthrough lands when that UI does (closing the gap issue must
remove the marker and add the walkthrough — an acceptance criterion on each).
Authoring a walkthrough (when a gap closes)
-
Add spec-generated per-step screenshots to the
journey-*spec; copy the PNGs todocs/modules/ROOT/assets/images/walkthroughs/<journey>/. -
Write
walkthroughs/<journey>.adoc— persona table, a numbered# | Who | Action | Expected outcome | Screenshotstep table referencingimage::walkthroughs/<journey>/step-NN.png[], and an[IMPORTANT]block naming the paired spec + the exactscenario.id. -
State the applicant precondition concretely — not just "apply". The worker steps are click-by-click; the applicant side must be equally reproducible. Name the specific inputs the journey depends on (e.g. two children under the ELE age gate; a public-assistance household eligible for both SNAP and TANF), or — when any eligible case works — say so and give sample values that reproduce the screenshots (household composition, income, key facts). Read those values from the paired spec’s given-library construction so the doc and the spec agree.
-
Replace the row’s
walkthrough_blocked_bywith awalkthroughbinding to the new page.cargo xtask scenarios auditverifies the pairing.