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.

TIP

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:

  1. the automated journey-*.spec.ts Playwright spec (the e2e-spec binding), and

  2. a human-followable walkthrough on this site (a walkthrough binding to an .adoc under 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 Actionsnap.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 actionsnap.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 → noticesnap.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 recomputesnap.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 hearingsnap.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 reportsnap.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 reapplicationsnap.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 overpaymentsnap.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 overpaymentsnap.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 certificationsnap.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 casesnap.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)

  1. Add spec-generated per-step screenshots to the journey-* spec; copy the PNGs to docs/modules/ROOT/assets/images/walkthroughs/<journey>/.

  2. Write walkthroughs/<journey>.adoc — persona table, a numbered # | Who | Action | Expected outcome | Screenshot step table referencing image::walkthroughs/<journey>/step-NN.png[], and an [IMPORTANT] block naming the paired spec + the exact scenario.id.

  3. 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.

  4. Replace the row’s walkthrough_blocked_by with a walkthrough binding to the new page. cargo xtask scenarios audit verifies the pairing.

Edit this page · default