Autonomous Fullpage UX Audit

Execute exhaustive visual verification across an app, then critique in batches after complete capture coverage. Store all outputs in .screenshots/YYYY-MM-DD_HH-MM/.

Prime Directives

1. Execute without permission loops.
2. Fix environment blockers instead of stopping at excuses.
3. Attach evidence to every claim (commands, paths, output snippets).
4. Capture full-height pages only.
5. Capture all routes before critique.
6. Critique in batches and compare Mobile/Tablet/Desktop.
7. Include authenticated routes via cookie or login automation.
8. Save all artifacts inside the repo under .screenshots/{session}/.
9. Read required source files end-to-end.
10. Never kill a running server.

Phase 1: Bootstrap

1. Read, in order:
   • package.json
   • .env* files
   • framework config (vite.config.*, next.config.*, etc.)
   • route surface (src/App.*, app/**, pages/**, router files)
   • README.md, CLAUDE.md, AGENTS.md
   • tailwind.config.*
   • .env.example*
2. Resolve BASE_URL without restarting healthy servers:
   • Probe likely ports (3000, 5173, 8080, 4173) with curl.
   • Prefer configured script/port from source.
3. Resolve authentication with this ladder:
   • Existing cookie/session env values
   • API login route discovered from code
   • Seed/create audit user when supported
   • UI login flow via Playwright and cookie export
   • Console document.cookie as last resort
4. Verify auth by calling a session endpoint or loading a protected route with no redirect.

Phase 2: Route Inventory

1. Extract routes using framework-native route discovery first.
2. Expand coverage using code search (href, to, path, navigate, router.push).
3. Add runtime-discovered routes from nav traversal.
4. Write .screenshots/{session}/route_inventory.json with all internal routes plus external links marked as EXTERNAL.
5. Produce a route table with columns: Route, Type, Auth, Priority, Notes.

Mark archetype flags where applicable:

• CANVAS_OPAQUE
• IFRAME_BLOCKED
• ANIMATED
• VIRTUALIZED
• SW_CACHED
• MEDIA_OPAQUE

Phase 3: Full-Page Capture

For each route and each breakpoint:

• Set viewport (mobile, tablet, desktop).
• Apply cache bypass when possible.
• Navigate with networkidle.
• Stabilize before capture:
  • disable animations/transitions
  • wait fixed settle delay
  • close non-critical overlays if they obstruct content
  • scroll to top
• Capture fullPage: true.
• If native full-page fails, stitch screenshots with overlap and record that method in MANIFEST.

Use consistent filenames:

• {index}_{slug}__{breakpoint}.png

Always write/update:

• .screenshots/{session}/MANIFEST.json

Phase 4: Batch Critique

Only start after capture completion for all reachable routes.

Use these batches by default (adapt to app routes):

• A Discovery
• B Conversion
• C Authenticated User
• D Merchant/Business
• E Admin
• F Auth + Edge States
• G CLS Two-Shot

Score each screen 0/1 against rubric dimensions in references/rubric-and-batches.md.

Phase 5: Deliverables

Write all files under .screenshots/{session}/:

• MANIFEST.json
• ISSUE_LOG.md
• SOURCE_LEDGER.md
• EXECUTIVE_SUMMARY.md

Use references/deliverables.md format.

Safety Systems

Anti-loop valve:

• After 3 repeated failures on one item, write root cause + attempts, mark BLOCKED, continue.

Completion gate:

• Each route has Mobile/Tablet/Desktop capture or documented exception.
• Every batch has at least one finding or explicit none.
• Source ledger includes read sources and unreachable items.
• Auth method is documented and reproducible.
• Failed captures are documented, never omitted.

Scripts

• scripts/init_audit_session.sh: create timestamped session folder and starter deliverables.
• scripts/check_completion_gate.sh: validate required files and basic gate conditions.

Execution Trigger

Begin immediately:

1. Read sources.
2. Validate server and auth.
3. Extract routes.
4. Capture all full-page screenshots.
5. Run batched critique.
6. Write deliverables.
7. Verify completion gate.