Behavior Audit — per-page flows, actions, edge cases

Purpose

Turn a working app into a severity-tagged, evidence-backed audit document (one section per page) that a human + agent can work through top-down in later bug-fix sessions. The doc is the deliverable — not fixes; fixing is a follow-up pass driven by the doc.

Proven pattern (first full run on a mid-size app → repo-root BEHAVIOR-AUDIT.md, ~90 findings, 7 verified high-severity bugs surfaced).

When to use

• User asks for behavioral flowcharts per page + what the user can do, to mine edge cases.
• User wants a UX/consistency/tips review as a working base for bug fixing.
• Trigger phrases include: "flowchart رفتاری هر صفحه", "کنار هر صفحه بذار", "edge case ها رو در بیار", "pages confusing, add tips/tutorial", "map every screen before we bug-fix".

Preconditions

• Source repo available; you know which directory holds the UI (frontend framework is irrelevant to the method — pages/views/screens all work).
• Status context helps but is optional: roadmap/CHANGELOG, prior session IDs the user references (pull with the client's session-history tool if available, focused query "known bugs, UX complaints, pending work").
• Context discipline: the main agent reads ONLY the app shell and spot-verifications. Prefer scoped delegation when available and authorized; otherwise audit bounded page areas sequentially with targeted reads. Lack of subagents is not a blocker.

Workflow

1. Scope the app (main agent — 2–3 cheap reads max): Read the shell (router/nav component, e.g. App.tsx + Sidebar) and the status doc. Enumerate: every page/view + every global overlay (dialogs answerable from any view, first-run guides, toast system). Record each page's mount semantics — does it unmount on navigation, or stay mounted/hidden? This single fact drives the biggest edge-case class (state loss vs listener leaks), so get it right up front.
2. Partition into exclusive scopes — one agent per page area. An area = the page component + its satellite components + skim-level access to the backend modules its commands depend on. Shared files (stores/api clients) may be read by all agents; no agent writes anything. Respect the client's actual concurrency limit; batch more areas in a second wave if needed.

3. Fan out Explore subagents in parallel. Each prompt is self-contained (absolute repo path, file list with line counts, "read each file once") and demands this exact report shape:

   1. Page purpose & entry points — how the user reaches it, when it shows/hides.
   2. User actions inventory — EVERY control (buttons, inputs, toggles, menus, keyboard, hover-only, icon-only + tooltips): what it does, which command/store it calls, disabled/hidden conditions.
   3. States & transitions — loading / empty / error / success / disabled / pending, and what triggers each; dialog flows; navigation in/out.
   4. Behavior flow — numbered step/branch journeys with explicit decision points.
   5. Edge cases & suspected bugs — concrete, each with file:line: unhandled rejections, silent catches, races/stale closures, unmount listener+state loss, double-click, dead code paths, validation gaps, toasts contradicting UI state, platform gaps.
   6. UX gaps & tip opportunities — confusing labels, missing feedback/empty states, first-use tip spots, inconsistencies with sibling pages.

   Hard rules inside every agent prompt: quote file:line for every claim · describe behavior and risks only — do NOT propose fixes · mark uncertain items "verify".

4. Pull history in parallel with step 3: status docs + prior sessions (see Preconditions). Session context feeds the appendix and explains "why is it like this", not new findings.
5. Verify before publishing. Static analysis overclaims. Pick the 3–5 highest-severity claims and confirm each yourself with a targeted grep/read. Confirm → keep 🔴; refuted → drop or downgrade with a note; unverified → keep but tag "verify first". (Finding classes from a real run: a dialog passing one argument into another (protocol string → password arg) — confirmed real; leftover dev mocks — confirmed but dev-only, downgraded; a truncated-read editor overwrite — confirmed real data-loss path.)
6. Write BEHAVIOR-AUDIT.md (repo root if the project keeps root-level docs, else its docs convention):
   • Header: basis version, audit date, how-to-use, severity legend (🔴 broken/data-loss — verify before fixing · 🟡 real bug/confusion risk · ⚪ polish).
   • Shell section: nav model, mount semantics, global overlays, app-level mermaid, global edge cases.
   • One section per page, each with: 1–2 line purpose/entry → mermaid flowchart (journey level) → "User can:" action list → numbered edge cases with severity + file:line → UX gaps & tips bullets.
   • Cross-page themes: recurring bug classes (fix once, heal N pages) + a suggested first fix batch (5–9 items, highest value first).
   • Appendix: environment/pending notes pulled from sessions. Keep the doc under 1000 lines — dense bullets, no prose padding.
7. Excalidraw renders (optional, on request or when annotated diagrams are wanted). The mermaid stays inline in the doc regardless (renders on GitHub). For editable diagrams, hand each page's flow to the excalidraw skill creation path: write a spec JSON (nodes/edges, diamond for the decision points you numbered, direction TB), then node ~/.agents/skills/excalidraw/scripts/generate_flow.mjs <spec>.json -o docs/diagrams/behavior-<page>.excalidraw.json and run validate.mjs on every output (exit 0 required). One diagram per page; the numbered decision points in the doc map 1:1 to the diamonds. Never hand-write or read the raw .excalidraw.json in the main context.
8. Wire the pointers + close: add a one-line pointer in the project's continuity file (roadmap.md / memory) so the next session finds the doc; final summary reports 🔴/🟡/⚪ counts, which 🔴s were manually verified, the top finds, and the suggested first fix batch; offer "pick a page, work its list top-down" as the next step.

Rules

• Keep code, identifying paths, screenshots and findings local for confidential applications. Historical examples above illustrate the method, not the current product.
• Distinguish source-derived behavior, rendered observations and suspected risks. Static evidence alone does not prove a race or visual defect reproduced; state needed verification without running destructive flows.
• Evidence or it doesn't go in. Every finding carries file:line. "I suspect" is not a finding; "suspected, verify first (file:line)" is.
• The audit is read-only. Findings only; fixes happen in a later pass the doc drives.
• Mount semantics before everything. Unmount-on-navigate → orphaned progress UI, dead completion toasts, state rehydration questions. Kept-mounted → window-wide listener leaks. Check both for every page.
• Retry failed agents (rate limit / timeout) instead of shipping a page gap; the audit is only as good as its thinnest section. Use bounded retries only for evidenced transient failures; otherwise inspect the area yourself or explicitly report it as unaudited.
• Mermaid hygiene: quote every node label, no bare parentheses, ≤ ~15 nodes per diagram; journeys longer than that live in the numbered flow list, not the diagram.
• Doc language English; keep it in the repo (continuity lives in the repo, not chat).
• Don't re-derive what roadmap/CHANGELOG already records — cite it; note divergences between docs and code as findings.

Common mistakes

• Publishing unverified 🔴s. Mock-only code paths, browser-dev branches, and dead code regularly masquerade as bugs from static reading. Step 5 exists for this.
• Skipping the shell/overlays. App-level dialogs (conflicts, approvals) and nav behavior carry cross-page bugs; auditing only the pretty pages misses them.
• Letting agents propose fixes. A polluted findings list doubles review effort; keep sections 5 and 6 descriptive, put remediation only in "Cross-page themes".
• Reading page files in the main context. 10k+ lines of UI blows the budget; the main agent's reads are the shell + verifications, nothing more.
• 50-node mermaid diagrams. Unreadable and fragile; journey-level diagrams + numbered flows beat encyclopedic graphs.
• Forgetting unmount checks because the page "works" — the bugs are in what happens when the user leaves mid-action, not in the happy path.

Validation

• Verify up to 3 highest-risk file:line claims (all if fewer exist), plus additional claims whose severity depends on uncertain behavior; record which 🔴s were verified vs "verify first".
• Coverage check: every nav item + every global overlay + the shell = one section; no orphan page or dialog.
• Every mermaid block passes an eyeball syntax pass (quoted labels, valid arrows); render once if a renderer is available.
• wc -l BEHAVIOR-AUDIT.md < 1000.
• Final summary includes severity counts per page, verified-vs-unverified split, and the first fix batch.
• If excalidraw diagrams were produced: validate.mjs exit 0 on every file, and the user was told how to open them.