# Flowaudit > Forensic user flow audit v2. 25-phase deep analysis of every user journey, workflow, state machine, edge case, error recovery, and experience gap. Covers flow mapping, state verification, dead-end detection, permission gaps, data integrity through flows, onboarding completeness, cross-session continuity, error recovery paths, accessibility of journeys, flow performance, plus verdict, fix plan, fix execution, re-audit, and integration smoke gate. Score /400. Preamble v1.0 compliant. Audit → Plan → Fix → Re-audit. Use when user says "/flowaudit", "audit the flows", "check user journeys", "workflow audit", "flow review". - Skill: `agentik-os/flowaudit` (Agent Skill) - Install (CLI): `npx skillmds@latest add agentik-os/flowaudit` - Raw SKILL.md: https://api.skillmd.com/api/skills/agentik-os/flowaudit/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: agentik-os (https://skillmd.com/u/agentik-os) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/agentik-os/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":""}`) 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: | Project type | /flowaudit behavior | Applicable max | |--------------|--------------------|-----------------| | **Next.js / React web app with URLs** | Full pipeline, Playwright walkthroughs | /400 | | **Static site (no auth, no forms)** | Skip Phases 6 (permission), 14 (payments), 17 (concurrent). Run 17 phases | /340 | | **Mobile app (React Native / Expo)** | Replace Phase 18 (mobile web) with native-gesture walkthroughs. Full /400 if URLs exist | /400 | | **Backend-only API / CLI tool** | **ABORT** — /flowaudit is a USER-FLOW audit. Route to `/apiaudit` for API contracts, `/dxaudit` for CLI UX instead. Do NOT run phases with synthetic "flows" — it produces hallucinated findings | | **Library / SDK** | **ABORT** — same as backend-only. Route to `/codeaudit` + `/dxaudit` + `/apiaudit` | | **Desktop app (Tauri, Electron)** | Run with caveats: Playwright's webview driver required; some phases (18 mobile) become N/A | | **Headless service / bot** | **ABORT** — no UI to walk through | **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: . 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) ```bash ~/.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//.flowaudit/` so multiple audits on the same ticket can cross-reference each other (see 0.5). ### 0.2 evidence-summary.json schema ```jsonc { "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-.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 ` (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//./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)