--- name: verifying-ux description: Live application verification procedure for the ux-reviewer agent — detect the project type (UI, API-only, or library), boot the application, exercise it with real requests, and evaluate the experience. Loaded when an implementation needs live smoke verification. user-invocable: false --- # Verifying UX The ux-reviewer's procedure: boot the application, interact with it as a real user would, and evaluate if the experience works correctly. ## Detection First, determine the project type by inspecting configuration files: - **UI project:** Has a frontend framework (React, Vue, Svelte, Next.js, etc.) with pages, components, or routes that render HTML. - **API-only project:** Has HTTP endpoints but no user-facing UI (REST API, GraphQL, CLI tool). - **Library:** No runnable server. Skip live testing and report that live verification is not applicable. ## UI Project Verification 1. **Start the dev server.** Find the applicable start command from `package.json` scripts, `Makefile`, or equivalent. Run it in the background. Wait for the server to be ready (watch for "ready" or "listening" output, or poll the port). 2. **Verify the home route.** Use `curl` to fetch the main page. Check that: - The response status is 200 - The response body contains expected HTML structure - No server-side error messages are present 3. **Check relevant pages.** If the implementation changed specific routes or pages, verify those routes return successfully. 4. **Check for console errors.** If the project has a test or health endpoint, hit it. Look for error indicators in the server output. 5. **Capture screenshots** while the server is still up — follow `## Screenshot Capture (UI projects)` below. 6. **Stop the dev server** when verification is complete. ## API Project Verification 1. **Start the server.** Find and run the applicable start command in the background. Wait for it to be ready. 2. **Send real HTTP requests** with `curl` to the endpoints affected by the implementation: - Verify response status codes are correct (200, 201, 404, etc.) - Verify response headers (Content-Type, CORS, etc.) - Verify response body structure matches expectations - Test error cases (invalid input, missing auth, not found) 3. **Check edge cases:** - Empty request bodies where a body is expected - Malformed input - Missing necessary parameters 4. **Stop the server** when verification is complete. ## Screenshot Capture (UI projects) Runs as step 5 of UI Project Verification, inside the server lifecycle (the server is up. You have not stopped it yet). Skip this entire section for API-only and Library projects. **UI-impact gate.** Capture only when both conditions hold: the project type is UI **and** the branch's full diff touches components, templates, pages, routes, or styles — check `git diff $(git merge-base HEAD)..HEAD`, never this round's delta alone, so a later round whose own commits look non-UI still recaptures everything the branch changed. Resolve `` with `git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'`, falling back to `main`. If either condition fails, create no `screenshots/` directory and no manifest — skip the rest of this section. **Wipe and recapture.** Delete the contents of `/screenshots/` before capturing, so stale images from earlier rounds never reach the PR. Because the gate keys on the full branch diff, every round that captures does so for the complete set — never a delta. `` is the `docs/plans//` path from your dispatch context. **Seed.** Run the target project's own seed mechanism if you can discover one (`db:seed`, a `seed` script, fixtures). If no seed exists or seeding fails, capture anyway — set `seeded: false` in the manifest and add a one-line `seed_note`. **Capture.** Use the Playwright CLI through Bash (e.g. `npx playwright screenshot`). Take viewport-size shots, not full-page — GitHub's 10MB attachment bound. Capture one PNG per affected page/state, including reproducible empty and error states. Name files `--.png`, zero-padded so listing order is stable, and write them to `/screenshots/`. **Data caution.** These images leave the machine — team-pr uploads them to GitHub during the PR phase. Do not capture routes or states that render secrets or real PII. Prefer seeded or synthetic data. If a route's only available state exposes real data, skip it and list it under `## Skipped`. **Caps and skip statuses.** - At most 10 shots per round, within a 5-minute total round budget and a 30s per-shot timeout (on timeout, skip that shot, record it under `## Skipped`, and continue). - Server never started → manifest `status: skipped-server-start` (the existing report-it-as-the-primary-finding rule still applies). - Playwright absent or its chromium install fails → `status: skipped-no-tool`. - Auth-gated routes are not captured — list each under `## Skipped` as `skipped-auth`. - More affected states than the cap allows → add the line "N more states not captured" under `## Skipped`. **Manifest.** Write `/screenshots/manifest.md` through a Bash heredoc with a **quoted delimiter** (`<<'EOF'`), so caption and `seed_note` text can never trigger `$()`/backtick expansion. The same discipline applies to every command in this section: pass variable content (routes, file paths, captions) single-quoted or as separate argv words — never interpolated into a command string. Frontmatter schema, exactly: ```yaml --- topic: # verbatim from design.md, like every artifact date: phase: implement round: # review round if the dispatch names one; otherwise 1 status: captured | partial | skipped-server-start | skipped-no-tool seeded: true | false seed_note: --- ``` Body: a `## Captured` section with one `### --.png` heading per shot carrying three bullets — `route:` (the URL path), `state:` (populated | empty | error), `caption:` (one sentence) — and a `## Skipped` section listing each skipped route/state with its reason. `status: captured` means every planned shot is present. `partial` means some were skipped. ## Rules - ALWAYS stop the dev server when you are done, even if verification fails. Use process IDs or `kill` to make sure that cleanup happens. - Do NOT change any code. You are a tester, not a fixer. - Do NOT test functionality unrelated to the recent implementation. - If the server fails to start, report that as the primary finding and stop. - Never commit screenshots to any branch or worktree — they are local scratch under `docs/plans//screenshots/` until team-pr uploads them. - Screenshot capture failure is a Could-Improve note in the report, never REQUEST CHANGES. - Keep curl commands and output in the report so findings are reproducible. - Time-bound your verification. If the server has not started within 60 seconds, report a startup failure.