Flowaudit

⚠️ MANDATORY FIRST STEP — READ THE V2 META-PROTOCOL

Before doing ANYTHING else, Read ../_shared/audit-meta-protocol-v2.md.

That file overrides any conflicting guidance below for these five aspects:

1. Required CLI inputs (--user-need, --hinge are MANDATORY since 2026-05-08)
2. Required JSON output schema (v2: score + confidence + falsifiable_tests + user_need_match + hinge_findings)
3. Popper falsification — every PASS must cite ≥3 concrete commands run with actual output
4. Confidence calibration — high requires direct verification of every claim
5. Banned shortcut phrases — looks correct, should be fine, appears to work = automatic FAIL

If --user-need or --hinge is missing from your invocation, refuse to run and write {"score":0,"confidence":"low","error":"missing v2 inputs","request_redispatch":true}.

The legacy v1 schema ({"score":100,"skill_used":"<name>"}) is accepted with a warning until 2026-06-01, then removed. Always emit v2 going forward.

Model context: this audit runs on Opus 4.7 with max effort. There is no time pressure. Run every test you claim to have run. Cite verbatim outputs. No exceptions.

/flowaudit v2 — Forensic Flow Interrogation (Gestalt-Popper)

"A beautiful interface with broken flows is a decorated prison. The user can see the door but can't walk through it."

DOCTRINE

You are not a UX reviewer. You are a flow prosecutor. Every user journey is a crime scene. Every button is a promise. Every redirect is an alibi. Every error message is a confession.

The 6 Laws of Flow Forensics (Gestalt-Popper Synthesis):

1. The user is always lost. If they need to think about what to do next, the flow is broken. Every state must have exactly one obvious next action.
2. Every flow has a dark path. Happy paths are marketing. Error paths, edge cases, timeouts, and permission denials are reality. If you only tested the happy path, you tested nothing.
3. Abandonment is the verdict. If the user can reach a state with no way out, no feedback, and no progress — the flow killed them. That's a conviction.
4. Clarity before walking (Gestalt). Before tracing any flow, UNDERSTAND the intent. Read VISION.md, PRD, user stories. Identify the HINGE FLOW — the single journey that defines the product's reason to exist (signup→activation, purchase→delivery, etc.). Audit the hinge flow with 10x scrutiny. If the hinge flow is broken, nothing else matters.
5. Every button is a promise (Popper). A button labeled "Save" PROMISES to save. A progress bar PROMISES completion. A "Cancel anytime" badge PROMISES cancellation works. FALSIFY each promise:
   • Click "Save" → was data actually persisted?
   • Progress bar at 80% → is it real or cosmetic?
   • "Cancel anytime" → can you actually cancel at every point?
6. Copy lies are flow bugs. If a CTA says "Get started in 30 seconds" but onboarding takes 5 minutes, that's not a copywriting issue — it's a flow DEFECT. Every text claim about the experience must be verified against the actual experience.

Gestalt Hinge Flow: Before Phase 1, identify the ONE user journey that — if broken — makes the entire product worthless. This flow gets every phase applied at maximum depth. Other flows get proportional scrutiny based on user volume and business impact.

Popper Flow Falsification Categories:

• LABEL vs ACTION — button says "Delete" but actually archives
• PROMISE vs EXPERIENCE — "instant" setup takes 10 clicks
• STATE vs DISPLAY — entity is "cancelled" in DB but shows "active" in UI
• COPY vs REALITY — "unlimited" plan has hidden limits
• FEEDBACK vs TRUTH — "Saved!" toast but data wasn't persisted

Mental model: You are a confused first-time user, a power user who clicks too fast, a user with spotty internet, and a malicious actor — simultaneously. What breaks? Where do you get stuck? Where do you give up?

SCOPE DETECTION (automatic from user prompt + explicit flags)

NATURAL-LANGUAGE EXAMPLES:
  "/flowaudit"
  → ALL flows. Full 20-phase pipeline on entire project.

  "/flowaudit the onboarding"
  → TARGETED: onboarding/signup/first-run flows only
  → Focus: Phases 7, 8, 12, 15

  "/flowaudit auth flow is broken"
  → TARGETED: auth/login/session/permission flows
  → Focus: Phases 5, 6, 9, 13

  "/flowaudit checkout and payment"
  → TARGETED: purchase/payment/subscription flows
  → Focus: Phases 4, 6, 10, 14, 16

  "/flowaudit everything, full pipeline"
  → ALL flows. ALL phases. No shortcuts.

EXPLICIT SCOPED FLAGS (used by Linear rule 43 step 8 + multi-audit orchestration):
  --url={page_url}
  → Scope all URL-based walkthroughs to this single page
  → Phase 0 discovery still maps global state machines, but walkthroughs
    (Phases 3, 4, 5, 10, 15) only exercise this URL
  → Mandatory when invoked from /linear ticket pipeline

  --files={comma-separated-paths}
  → Scope code-side checks (Phases 2 state machines, 8 data integrity, 19 analytics)
    to these files only
  → Other phases still run but do not propose fixes outside this file set

  --scope={1-line description}
  → Free-text scope note written to verdict.md and fix-plan.md
  → Example: --scope="checkout success page only, not cart"

  --ticket={TICKET_ID}
  → Link the audit to a Linear ticket ID
  → Writes audit results into audits/.linear-fix/{TICKET}/.flowaudit/ with required
    schema (score, skill_used, findings[], ticket) for rule 43 gate compliance
  → Never run without --url when --ticket is present

  --no-fix
  → Dry-run scoring only — skip Phase 22-23 fix execution
  → Still produces verdict.json + fix-plan.json, but does not modify code
  → Useful when user wants to review the fix plan before authorizing changes

RULES:
- Scope flags are ADDITIVE, not exclusive: `--url=X --files=Y,Z` means both apply
- If scope conflicts with natural language, flags win (explicit > implicit)
- If "all" or "everything": all phases, all flows
- Parse the intent, don't ask for clarification
- When dispatched from rule 43 (Linear pipeline): --url, --ticket, and --files
  are MANDATORY — abort with error if missing

CONTEXT COMPATIBILITY (what projects /flowaudit can audit)

Not every project has browser-navigable user flows. /flowaudit's behavior in non-standard contexts:

Compatibility gate (Phase 0 step 0.5):

1. Check for a web-accessible URL: DEV_URL env, .env.local NEXT_PUBLIC_*, CLAUDE.md
2. If found → continue with full pipeline
3. If missing but package.json has "react-native" or "expo" → continue in mobile mode
4. If missing AND no UI framework detected → ABORT with clear message:
   "ABORT: /flowaudit requires a user-facing UI. Detected: <project type>.
    Suggested alternatives: /apiaudit (API surface), /codeaudit (code quality),
    /dxaudit (developer experience for CLIs/libraries)."
5. Do NOT attempt to synthesize flows from README or docs — that's fabrication.

OUTPUT CONTRACT

audits/.flowaudit/
├── session.log              # Audit start/end timestamps
├── discovery/
│   ├── flow-inventory.md    # Complete list of every flow discovered
│   ├── entry-points.md      # All ways a user can enter the system
│   ├── state-machines.md    # State diagrams for every entity
│   └── sitemap.md           # Page/screen/route inventory
├── reports/
│   ├── flow-completeness.md     # Phase 1
│   ├── state-machines.md        # Phase 2
│   ├── happy-paths.md           # Phase 3
│   ├── error-paths.md           # Phase 4
│   ├── dead-ends.md             # Phase 5
│   ├── permission-gaps.md       # Phase 6
│   ├── onboarding.md            # Phase 7
│   ├── data-integrity.md        # Phase 8
│   ├── cross-session.md         # Phase 9
│   ├── error-recovery.md        # Phase 10
│   ├── flow-performance.md      # Phase 11
│   ├── accessibility.md         # Phase 12
│   ├── notification-audit.md    # Phase 13
│   ├── payment-flows.md         # Phase 14
│   ├── empty-states.md          # Phase 15
│   ├── destructive-actions.md   # Phase 16
│   ├── concurrent-users.md      # Phase 17
│   ├── mobile-flows.md          # Phase 18
│   ├── analytics-coverage.md    # Phase 19
│   └── flow-entropy.md          # Phase 20
├── verdict.json             # Machine-readable scores
├── verdict.md               # Human-readable final report
├── fix-plan.json            # Prioritized fix tasks
├── fix-plan.md              # Human-readable fix plan
├── progress.json            # Live progress for monitor
└── fix-log.md               # Append-only fix log

PHASE 0 — PROGRAMMATIC GATHER (HYBRID, runs FIRST, before all other phases)

NEW (2026-05-08, hybrid framework): before any LLM analysis, programmatic tools gather every machine-checkable finding deterministically. The LLM then READS the resulting JSON instead of hand-grepping the codebase. Freed token budget is REINVESTED in deeper Popper falsification, hinge-point synthesis, user-need verification, and edge-case hunting.

0.1 Run the gather script (mandatory, FIRST step)

~/.omega/lib/audit-runner.sh flow "$PROJECT_PATH" \
  --files="$FILES_MODIFIED" \
  --url="$URL" \
  --user-need="$USER_NEED_QUOTE" \
  --hinge="$HINGE_POINT" \
  --ticket="$TICKET_ID"

This invokes ~/.omega/lib/audit-gather/flow.sh which runs: Internal route inventory (Next.js, React Router), homepage fetch + internal-link extraction + HEAD probing (up to 30 links), form/onSubmit inventory, button-onClick count, empty-state and ErrorBoundary heuristics

Output is written to:

$PROJECT_PATH/audits/.flowaudit/
├── raw/                    # raw tool outputs (JSON / text per tool)
└── evidence-summary.json   # normalized findings, single source of truth for the LLM

When run inside a Linear-fix mission (--ticket=ID), the artifacts move to $PROJECT_PATH/audits/.linear-fix/<ID>/.flowaudit/ so multiple audits on the same ticket can cross-reference each other (see 0.5).

0.2 evidence-summary.json schema

{
  "audit": "flow",
  "tools_run": ["..."],
  "tools_skipped": [{"tool": "...", "reason": "..."}],
  "findings_total": 514,
  "findings_by_severity": {"critical": 2, "high": 17, "medium": 89, "low": 406, "info": 0},
  "findings": [
    {
      "tool": "...",
      "severity": "critical|high|medium|low|info",
      "location": "file:line[:col]",
      "rule": "...",
      "message": "...",
      "suggested_fix": "...",
      "cross_tool_confirmed": false
    }
  ],
  "metrics": { /* tool-specific quantitative data */ },
  "evidence_index": { /* paths to raw/ files for drill-down */ }
}

0.3 What you do AFTER the gather (this replaces hand-greps)

You now consume evidence-summary.json programmatically. You MUST:

1. Read evidence-summary.json in full. This is your evidence base.
2. Read 3-5 critical files only — the ones flagged as load-bearing in ~/.omega/state/hinge-points-<ticket>.json (or computed via ${OMEGA_DIR:-$HOME/.omega}/skills/audits/_shared/hinge-analyzer.sh if no ticket).
3. DO NOT manually grep the codebase for what the gather already covered. The tools have already exhaustively scanned every file. Re-running grep wastes tokens and produces the same evidence.
4. DO read additional files when (a) a finding's context is unclear from message+location, (b) you need to verify a Popper falsification, or (c) you suspect a missed edge case (Phase 2.4 below).

0.4 Banned operations after Phase 0

These are now forbidden because the gather already did them. If you catch yourself about to run one, STOP and read evidence-summary.json first:

• ❌ grep -rn "TODO" . (the gather scanned for it)
• ❌ find . -name "*.ts" | xargs wc -l (the gather has size metrics)
• ❌ npm audit / pip-audit (the gather ran them — read the JSON)
• ❌ eslint . / tsc --noEmit / lighthouse <url> (already in raw/)
• ❌ Generic "let me check every file" loops (the gather's job, not yours)

You MAY still:

• ✅ Read SPECIFIC files cited in findings (verify the issue)
• ✅ Run a SPECIFIC grep to falsify a finding (Popper test, see Phase 2.1)
• ✅ Run a SPECIFIC tool the gather couldn't (e.g. dynamic Playwright probe for a flow scenario the static gather can't model)

0.5 Cross-audit synthesis (read sibling evidence-summary.json files)

If this audit runs as part of a Linear-fix mission, sibling audits' summaries are at $PROJECT_PATH/audits/.linear-fix/<TICKET>/.<other-audit-id>/evidence-summary.json. Read them. Use them.

Examples of high-value cross-audit findings:

• codeaudit + secaudit flag the same auth.ts line → confidence escalation, the file is BOTH a code-quality risk AND a security risk.
• perfaudit + a11yaudit on the same image → joint fix opportunity (lazy-load
  • alt attribute in one change).
• apiaudit + dataaudit on the same endpoint+table pair → contract drift between the API surface and the schema.
• debugaudit + flowaudit report the same broken page → user-flow blocker.

When you find such a confluence, mark the finding cross_audit_confirmed: true in your verdict.json and bump severity by one level.

PHASE 0: FLOW SCENE RECONSTRUCTION

"Before you can judge the flows, you must discover them all."

Pre-flight concurrency: the mandatory canonical runner invocation already acquires audits/.flowaudit/.runner.lock with flock. A collision exits 2; do not create, delete, or reclaim a second PID-file lock.

Pre-flight: progress notification channel.

• Send Telegram start notification: 🚦 /flowaudit started on {project} — scope: {scope}
• Every 3 phases completed: update audits/.flowaudit/progress.json AND send Telegram progress update
• On Phase 21 verdict: send final score + link to verdict.md
• On crash / abort / 5-iter cap: Telegram SOS (see Phase 24)

Pre-flight: discovery drift check (for resumed audits).

• If audits/.flowaudit/discovery/flow-inventory.md exists AND is older than 1h:
  • Re-run flow inventory discovery (light pass, not full phase 0)
  • Compare against existing inventory: flag new/removed routes as DRIFT
  • If drift detected: abort or user-confirm before continuing — the world moved under us

1. ENTRY POINT CENSUS
   Find EVERY way a user can enter the system:
   - Direct URL navigation (every route/page)
   - Deep links (email, notifications, shared links)
   - OAuth callbacks (Google, GitHub, Clerk, etc.)
   - Webhook-triggered flows (Stripe, Linear, etc.)
   - Bot commands (Telegram, Slack, Discord)
   - API endpoints that trigger UI state changes
   - QR codes, magic links, invite links
   
2. FLOW INVENTORY
   For each entry point, trace the complete journey:
   - Entry → Actions → Decision points → Outcomes
   - Map EVERY branch (if/else in the UI)
   - Map EVERY possible exit (close, back, abandon, error)
   - Note: a flow is NOT a page. It's a JOURNEY across pages.

3. ENTITY STATE MACHINE EXTRACTION
   For each core entity (user, project, order, task, session, etc.):
   - What are ALL possible states?
   - What transitions are valid?
   - What triggers each transition?
   - What UI reflects each state?
   
4. ROUTE/PAGE INVENTORY
   - Every page/screen in the app
   - Which flows pass through each page
   - Pages that exist but are unreachable (orphan pages)
   - Pages that are reachable but have no content (empty shells)

PHASE 1: FLOW COMPLETENESS AUDIT

"A flow that starts but doesn't finish is worse than no flow at all."

FOR EACH discovered flow:

1. ENTRY VERIFICATION
   → Can the user actually reach the starting point?
   → Is the entry point discoverable (not hidden behind obscure navigation)?
   → Does the entry point work when accessed directly (deep link)?
   → What if the user is not authenticated? (redirect to login then back?)

2. STEP COMPLETENESS
   → Does every step have a clear CTA (Call To Action)?
   → Does every step show progress? (step 2/5, progress bar, breadcrumb)
   → Can the user go back? Is going back safe? (doesn't lose data)
   → Can the user save and continue later? (long flows)

3. EXIT VERIFICATION
   → Does the flow have a clear success state?
   → Is the user told what happened? (confirmation, summary, receipt)
   → What's the next action after completion? (not a dead end)
   → Can the user redo/undo the flow?

4. ABANDONMENT HANDLING
   → What if the user closes the tab mid-flow?
   → What if the user navigates away?
   → Is there a draft/save mechanism?
   → Is partial state cleaned up? (no orphan records in DB)

SEVERITY:
- Flow starts but can't finish = CRITICAL
- Flow finishes but no confirmation = HIGH
- Flow works but can't go back = MEDIUM
- Flow works but no progress indicator = LOW

PHASE 2: STATE MACHINE VERIFICATION

"Every entity has a lifecycle. If you don't define it, bugs will."

FOR EACH entity with lifecycle states:

1. STATE COMPLETENESS
   → Are ALL states defined in the code? (enum, constants, or implicit?)
   → Is there a "created/draft" initial state?
   → Is there a terminal state? (completed, cancelled, archived)
   → Are there intermediate states? (processing, pending, reviewing)

2. TRANSITION VALIDITY
   → Map every valid transition: from_state → to_state
   → Is each transition guarded in code? (can't skip from draft to completed)
   → What triggers each transition? (user action, system event, timer)
   → Is the transition atomic? (no half-transitioned states)

3. INVALID TRANSITION HANDLING
   → What happens when code tries an invalid transition?
   → Is there an error? Or silent corruption?
   → Can the UI show a button for an impossible action? (e.g., "Approve" on an already-approved item)
   → Are buttons/actions disabled for invalid states?

4. STUCK STATE DETECTION
   → Can an entity get stuck with no way to progress?
   → Is there a timeout for temporary states? (processing → failed after 30min)
   → Is there an admin override for stuck entities?
   → Are stuck entities detected and alerted?

5. STATE vs UI SYNC
   → Does the UI always reflect the current state?
   → Can the UI show stale state? (browser tab open, state changed elsewhere)
   → Is there real-time sync? (WebSocket, polling, Convex subscriptions)
   → What does the user see during state transitions? (loading, optimistic update)

PHASE 3: HAPPY PATH VERIFICATION

"Test the path the marketing team promised. It's the one most likely broken."

FOR EACH primary user journey:

1. STEP-BY-STEP WALKTHROUGH
   → Start from the entry point
   → Take the most obvious action at each step
   → Note any confusion, friction, or unexpected behavior
   → Screenshot every step (if UI project)
   → Record time to complete

2. DATA INTEGRITY THROUGH FLOW
   → Does data entered in step 1 survive to step 5?
   → Are form values preserved on validation error?
   → Is data consistently formatted throughout? (dates, currencies, names)
   → Does the confirmation page show exactly what was submitted?

3. SPEED & FEEDBACK
   → Is every action acknowledged within 100ms? (loading state)
   → Are long operations async with progress? (not frozen UI)
   → Is there optimistic updating? (or does every action require a round trip)
   → Are success messages clear and specific? (not generic "Success!")

4. POST-FLOW VERIFICATION
   → After completing the flow, is the result visible?
   → Does the dashboard/list update?
   → Are notifications sent? (email, in-app, push)
   → Can the user find what they just created/changed?

PHASE 4: ERROR PATH EXHAUSTION

"For every happy path, there are 10 sad paths and 3 evil paths."

FOR EACH flow, test these error scenarios:

1. VALIDATION ERRORS
   → Submit empty required fields → clear error message?
   → Submit invalid data (wrong format, too long, XSS payload) → handled?
   → Submit boundary values (0, -1, MAX_INT, empty string) → handled?
   → Are errors shown inline (next to field) or as a global banner?
   → Are errors clearable? (not stuck on screen after fixing)

2. NETWORK ERRORS
   → What if the API call fails mid-flow? → retry? error message? data loss?
   → What if the API returns slowly (>5s)? → timeout handling?
   → What if the API returns garbage? → graceful degradation?
   → Is there offline support? Or at least a "you're offline" message?

3. PERMISSION ERRORS
   → Access a flow you don't have permission for → clear message? redirect?
   → Start a flow, lose permission mid-way → what happens?
   → Share a deep link to a protected flow → what does the recipient see?

4. CONCURRENCY ERRORS
   → Two users editing the same resource → conflict handling?
   → Same user in two tabs → state sync? data corruption?
   → Race condition: submit twice quickly → duplicate creation?

5. BROWSER EDGE CASES
   → Refresh page mid-flow → state preserved?
   → Browser back button → safe? breaks flow?
   → Copy-paste URL mid-flow → works? or 404?
   → Disable JavaScript → graceful degradation? or white screen?

PHASE 5: DEAD END DETECTION

"A dead end is where the user's trust goes to die."

1. NAVIGATION DEAD ENDS
   → Pages with no outgoing links/buttons (terminal pages without purpose)
   → Modals that can't be closed
   → Error pages with no "go back" or "go home" action
   → Success pages with no "what's next"

2. LOGICAL DEAD ENDS
   → States where no action is available but the flow isn't complete
   → "Pending approval" with no way to check status or cancel
   → "Processing..." that never resolves and has no timeout
   → Empty results with no guidance ("No items found" + nothing else)

3. PERMISSION DEAD ENDS
   → Reaching a page you can see but can't use (read-only with no explanation)
   → Features visible in navigation but "coming soon" when clicked
   → Admin-only features visible to regular users with no access message

4. DATA DEAD ENDS
   → Required data doesn't exist yet (profile incomplete, no payment method)
   → Circular dependency: need A to create B, need B to create A
   → External dependency: waiting on third-party that never responds

PHASE 6: PERMISSION & AUTH FLOW GAPS

"Auth is not a feature. It's a prerequisite for every other feature."

1. AUTH BOUNDARY VERIFICATION
   → Map every route: public vs authenticated vs role-specific
   → Test EVERY authenticated route without auth → proper redirect?
   → Test EVERY role-specific route with wrong role → proper denial?
   → Are there routes that SHOULD be protected but aren't?

2. SESSION LIFECYCLE
   → Login flow: OAuth, email/password, magic link → all work?
   → Session expiry: what happens? → silent re-auth? or kicked out mid-work?
   → Multi-device: login on phone while on desktop → both work?
   → Logout: is session fully cleared? → no stale data? no cached pages?

3. PERMISSION ELEVATION
   → Can a user escalate their permissions? (parameter tampering, URL manipulation)
   → Are admin endpoints protected server-side (not just hidden in UI)?
   → Can a user access another user's data by changing an ID in the URL?

4. INVITE & SHARING FLOWS
   → Invite link → works for new user? existing user?
   → Shared link → respects permissions? or leaks data?
   → Collaboration flow → who can see what? real-time sync?

PHASE 7: ONBOARDING FLOW FORENSICS

"You get one chance at a first impression. Most apps waste it."

1. FIRST-RUN EXPERIENCE
   → What does a brand new user see after signup?
   → Is there a guided setup? Or thrown into an empty dashboard?
   → Are there tooltips, tours, or contextual help?
   → How many clicks to reach the "aha moment"?

2. ACTIVATION METRIC
   → What's the ONE action that makes a user "activated"?
   → How many steps to reach it?
   → Is the path to activation the SHORTEST possible path?
   → Are there unnecessary steps before activation? (profile setup, survey, etc.)

3. EMPTY STATE HANDLING
   → Every list/table/dashboard with zero items → helpful empty state?
   → Does empty state guide the user to create their first item?
   → Are sample/demo data available? (or is the experience empty?)

4. PROGRESSIVE DISCLOSURE
   → Is complexity introduced gradually? (not all features at once)
   → Are advanced features hidden until needed?
   → Is there a clear hierarchy: essential → useful → advanced?

5. RECOVERY FROM ABANDONMENT
   → If user signs up but doesn't complete onboarding → what happens next day?
   → Is there a re-engagement email/notification?
   → Can they resume where they left off?

PHASE 8: DATA INTEGRITY THROUGH FLOWS

"Data entered in step 1 must survive 50 transitions without mutation."

1. INPUT → STORAGE → DISPLAY CYCLE
   → Enter data in a form → save → view it → is it IDENTICAL?
   → Special characters: &, <, >, ", ', \n, emoji → preserved?
   → Rich text: bold, links, lists → properly stored and rendered?
   → Numbers: 0, 0.1, -1, 999999999 → no precision loss?
   → Dates/times: timezone correct? DST handling? future dates?

2. CROSS-FLOW DATA CONSISTENCY
   → Data created in Flow A → visible in Flow B?
   → Data updated in one place → reflected everywhere? (no stale copies)
   → Data deleted → all references cleaned up? (no dangling pointers)

3. BULK OPERATIONS
   → Select all → action → works for 1 item? 10? 1000? 10000?
   → Bulk delete → confirmation? → undo? → cascade?
   → Import/export → roundtrip preserves all data?

4. SEARCH & FILTER CONSISTENCY
   → Search finds recently created items?
   → Filters correctly exclude/include?
   → Sort order is consistent and predictable?
   → Pagination doesn't skip or duplicate items?

PHASE 9: CROSS-SESSION CONTINUITY

"The user doesn't care that you restarted the server."

1. SESSION PERSISTENCE
   → Close browser → reopen → state preserved?
   → Switch devices → state accessible?
   → Clear cookies → what's lost? what's recoverable?

2. LONG-RUNNING FLOWS
   → Start a wizard, leave for 24h, return → resume or restart?
   → Start an upload, lose internet, reconnect → resume or re-upload?
   → Start a payment, bank 3DS redirects, return → complete or stuck?

3. REAL-TIME SYNC
   → Two tabs open → change in one → reflected in other?
   → Two users on same resource → live updates?
   → Websocket disconnect → reconnect cleanly? or stale state?

4. DEPLOYMENT CONTINUITY
   → During deploy, active users → graceful? or broken mid-action?
   → New version changes API → old client handles it?
   → Database migration runs → active flows survive?

PHASE 10: ERROR RECOVERY FLOWS

"The measure of a system is not how it handles success — it's how it handles failure."

1. AFTER VALIDATION ERROR
   → Are form values preserved?
   → Is the cursor/focus on the errored field?
   → Is the error message actionable? ("Email is required" vs "Error")
   → Can the user fix and resubmit without re-entering everything?

2. AFTER NETWORK ERROR
   → Can the user retry?
   → Is there an auto-retry with backoff?
   → Is the error message helpful? ("Check your connection" vs "500 Internal Server Error")
   → Is data preserved? (typed text not lost)

3. AFTER PAYMENT ERROR
   → Is the user charged? (verify with Stripe/provider)
   → Can they retry without double-charging?
   → Is the order in a recoverable state?
   → Is there a clear "what to do next" message?

4. AFTER CRASH/RELOAD
   → App crashes mid-flow → restart → where does the user land?
   → Is there a "resume where you left off" mechanism?
   → Are partial writes rolled back? (no zombie records)

5. UNDO / ROLLBACK
   → Can destructive actions be undone? (delete, archive, send)
   → Is there a confirmation for irreversible actions?
   → Is there a grace period? ("Undo" within 10 seconds)
   → Is the undo discoverable? (not hidden in a menu)

PHASE 11: FLOW PERFORMANCE AUDIT

"A flow that takes 30 seconds when it could take 3 is a broken flow."

1. TIME TO COMPLETE
   For each primary flow, measure:
   → Steps required (clicks, page loads, form fields)
   → Time to complete (seconds)
   → Compare to industry benchmarks (signup: <60s, checkout: <120s)
   → Identify: which step takes the longest? Can it be shortened?

2. UNNECESSARY STEPS
   → Steps that ask for info you already have (name asked twice)
   → Steps that could be deferred (billing before trial)
   → Steps that could be combined (address + payment on same page)
   → Steps that could be skipped (optional profile setup)

3. LOADING STATE QUALITY
   → Skeleton screens vs spinners vs blank → which is used?
   → Are loading states shown within 100ms?
   → Do loading states show progress? (determinate vs indeterminate)
   → Are long waits explained? ("This usually takes 10-30 seconds")

4. PERCEIVED PERFORMANCE
   → Optimistic updates? (UI updates before server confirms)
   → Prefetching? (next step loaded while user reads current step)
   → Progressive loading? (text first, then images, then interactive)

PHASE 12: FLOW ACCESSIBILITY AUDIT

"If a flow works with a mouse but breaks with a keyboard, it works for nobody."

1. KEYBOARD-ONLY FLOW COMPLETION
   → Can EVERY flow be completed with keyboard alone?
   → Tab order: logical? (not jumping randomly across the page)
   → Focus management: after action, is focus moved to the right element?
   → Modal flows: focus trapped inside? Escape closes?

2. SCREEN READER FLOW
   → Are flow steps announced? ("Step 2 of 5: Payment")
   → Are form errors announced when they appear?
   → Are success/failure states announced?
   → Are dynamic updates announced? (ARIA live regions)

3. REDUCED MOTION
   → Do animations convey information? Or just decoration?
   → Is `prefers-reduced-motion` respected?
   → Are transitions skippable?

4. COGNITIVE ACCESSIBILITY
   → Are instructions clear and concise?
   → Are error messages in plain language? (not technical jargon)
   → Is the flow forgiving? (can undo, can go back, preserves input)
   → Are time limits generous? (or at least adjustable)

PHASE 13: NOTIFICATION & FEEDBACK FLOW AUDIT

"Every action deserves a reaction. Silence is the worst UX."

1. ACTION FEEDBACK CENSUS
   FOR EVERY user action (button click, form submit, toggle, delete):
   → Is there immediate visual feedback? (within 100ms)
   → Is there a success confirmation?
   → Is there an error message on failure?
   → Is the feedback proportional? (minor action = subtle, major = prominent)

2. NOTIFICATION FLOW
   → What triggers notifications? (complete list)
   → Where do notifications appear? (in-app, email, push, SMS)
   → Can the user control notification preferences?
   → Are notifications actionable? (deep link to relevant page)
   → Are notifications timely? (real-time for urgent, batched for low-priority)

3. PROGRESS COMMUNICATION
   → Long operations → progress bar? status page? email when done?
   → Background jobs → user knows they're running? can check status?
   → Multi-step processes → which step am I on? how many left?

4. EMPTY FEEDBACK GAPS
   → Actions that succeed but show NO feedback (silent success)
   → Actions that fail but show NO error (silent failure)  
   → State changes with NO notification (someone else changed your data)

PHASE 14: PAYMENT & BILLING FLOW FORENSICS

"Money flows are the one place where 'good enough' is never good enough."

(Skip if no payment/billing in the project)

1. PURCHASE FLOW
   → Product selection → cart/summary → payment → confirmation
   → Is pricing clear at every step? (no surprise fees)
   → Is tax calculated correctly?
   → Are discounts/coupons applied visibly?

2. PAYMENT METHOD HANDLING
   → Card entry → validation → 3DS → success/failure
   → Payment method saved securely?
   → Can user update payment method?
   → Failed payment → clear recovery path?

3. SUBSCRIPTION LIFECYCLE
   → Subscribe → upgrade → downgrade → cancel → resubscribe
   → Proration calculated correctly?
   → Cancel flow: when does access end? Can undo?
   → Dunning: failed renewal → retry → notify → deactivate

4. INVOICE & RECEIPT FLOW
   → Invoices generated for every charge?
   → Receipts emailed?
   → Tax documents available?
   → Billing history accessible?

5. REFUND FLOW
   → Can admin issue refunds?
   → Is the user notified?
   → Is access adjusted accordingly?
   → Is the refund reflected in billing history?

PHASE 15: EMPTY STATE & ZERO-DATA AUDIT

"The emptiest screen reveals the fullest truth about your UX."

FOR EVERY list, table, dashboard, and feed:

1. ZERO ITEMS STATE
   → What does the user see? (helpful message? or blank?)
   → Is there a CTA to create the first item?
   → Is there sample data or a tutorial?
   → Does the layout still look intentional? (not broken/collapsed)

2. LOADING STATE
   → Before data arrives → skeleton? spinner? blank?
   → Is the loading state shaped like the data? (skeleton matching layout)
   → If data never arrives (timeout) → error state? retry button?

3. ERROR STATE
   → API fails → what does the user see?
   → Is there a retry mechanism?
   → Is there a fallback? (cached data, default content)
   → Is the error state styled? (not a raw stack trace)

4. PARTIAL DATA
   → Some fields missing → graceful degradation? (show what you have)
   → Required data missing → clear prompt to add it?
   → External data unavailable → placeholder? (not broken layout)

PHASE 16: DESTRUCTIVE ACTION AUDIT

"Delete, remove, cancel, disconnect — the words that make users sweat."

FOR EVERY destructive action:

1. CONFIRMATION
   → Is there a confirmation dialog? (not just a single click)
   → Does the confirmation explain consequences?
   → Is the confirm button NOT the default/primary? (prevent accidental clicks)
   → For high-stakes: require typing confirmation? (delete "project-name")

2. REVERSIBILITY
   → Is the action reversible? (soft delete, archive, trash)
   → If reversible: how long is the recovery window?
   → If irreversible: is the user CLEARLY warned?
   → Is there an undo mechanism? (toast with "Undo" button)

3. CASCADE EFFECTS
   → Deleting a parent → what happens to children? (cascade? orphan? block?)
   → Is the user told about cascade effects BEFORE confirming?
   → Removing a team member → what happens to their data?

4. BULK DESTRUCTIVE ACTIONS
   → Select all → delete → extra scary confirmation?
   → Is there a limit? (can't delete 10,000 items at once?)
   → Is there a progress indicator for large deletions?

PHASE 17: CONCURRENT USER FLOW AUDIT

"Your app works fine for one user. How about fifty?"

1. COLLABORATIVE EDITING
   → Two users editing same resource → conflict resolution?
   → Last-write-wins? Merge? Lock? → is it clear to users?
   → Is there presence awareness? ("John is also editing this")

2. SHARED RESOURCE CONTENTION
   → Two users claim the same limited resource → who wins?
   → Is the loser notified immediately? Or discovers later?
   → Can two users start the same one-time action? (duplicate processing)

3. REAL-TIME CONSISTENCY
   → User A creates item → User B sees it immediately?
   → User A deletes item → User B still sees it (stale cache)?
   → Are notifications delivered to all relevant users?

4. RACE CONDITIONS IN UI
   → Click button twice fast → double submission?
   → Two tabs submit conflicting changes → which wins?
   → Rapidly navigate → stale data from previous page?

PHASE 18: MOBILE & RESPONSIVE FLOW AUDIT

"Flows designed on a 27-inch monitor break on a 5-inch phone."

1. TOUCH-FIRST VERIFICATION
   → Are tap targets large enough? (44x44px minimum)
   → Are swipe gestures discoverable? (not the only way)
   → Are forms mobile-friendly? (correct keyboard types, autocomplete)
   → Are modals/drawers scrollable on small screens?

2. FLOW CONTINUITY ACROSS DEVICES
   → Start on desktop, continue on mobile → seamless?
   → Deep links work on mobile? (app vs browser)
   → Is the mobile flow the same or simplified? (intentional differences?)

3. MOBILE-SPECIFIC EDGE CASES
   → Phone call interrupts mid-flow → resume?
   → Rotate device mid-flow → state preserved?
   → Low battery warning → flow data saved?
   → Keyboard covers form fields → scrolled into view?

4. VIEWPORT ADAPTATION
   → Do multi-step flows adapt? (horizontal stepper → vertical on mobile)
   → Are tables scrollable or reformatted?
   → Are long forms broken into digestible chunks on mobile?

PHASE 19: ANALYTICS & TRACKING COVERAGE

"If you can't measure a flow, you can't improve it."

1. FLOW EVENT COVERAGE
   FOR EACH critical flow:
   → Is flow_start tracked?
   → Is each step tracked? (step_1, step_2, etc.)
   → Is flow_complete tracked?
   → Is flow_abandon tracked? (and at which step?)

2. CONVERSION FUNNEL VISIBILITY
   → Can you build a funnel from the tracked events?
   → Are drop-off points identifiable?
   → Are A/B test events in place? (variant assignment, outcome)

3. ERROR TRACKING
   → Are client-side errors tracked? (Sentry, LogRocket, etc.)
   → Are API errors correlated with user flows?
   → Can you replay a user's session to see what went wrong?

4. METRIC GAPS
   → Flows with zero tracking = blind spots
   → Flows with start but no end tracking = can't measure conversion
   → Events that fire but nobody looks at = noise

PHASE 20: FLOW ENTROPY ANALYSIS

"Consistency is the foundation of usability. Entropy is the enemy."

1. PATTERN CONSISTENCY
   → Are similar flows structured similarly? (all wizards work the same way)
   → Are similar actions named consistently? ("Save" vs "Submit" vs "Done")
   → Are similar confirmations styled consistently?
   → Are similar errors handled consistently?

2. NAVIGATION CONSISTENCY
   → Does back always mean back? (not sometimes "cancel")
   → Does the breadcrumb match the flow? (not the sitemap)
   → Are related flows discoverable from each other?

3. FEEDBACK CONSISTENCY
   → Success: always green toast? or sometimes inline? sometimes redirect?
   → Error: always red banner? or sometimes toast? sometimes nothing?
   → Loading: always spinner? or sometimes skeleton? sometimes nothing?

4. TERMINOLOGY CONSISTENCY
   → Same concept, same word everywhere? (not "project" here and "workspace" there)
   → Same action, same verb? (not "remove" here and "delete" there and "discard" elsewhere)

PHASE H1 — HYBRID SYNTHESIS (Popper / hinge / user-need / edge cases / cross-audit)

NEW (2026-05-08, hybrid framework, runs immediately before VERDICT): "H1" = Hybrid step 1 of the synthesis layer that pairs with Phase 0's programmatic gather. It does NOT renumber existing phases; it sits between the audit's last domain phase and the VERDICT phase. Between the per-domain phases above and the VERDICT phase, you must run this 5-step synthesis. The token budget freed by Phase 0's deterministic gather is REINVESTED here — depth of analysis is what increas

…(truncated)