Bug Sweep

---
name: bug-sweep
description: "Methodically walks a running app — every public route, every interactive control, every state (empty/loading/error/auth/un-auth) — to find real bugs, then root-causes, fixes, adds a regression test, and verifies each one before moving to the next. Use when: 'find bugs in the app', 'sweep for regressions', 'methodically hunt and fix bugs', 'audit user flows', 'find broken buttons / forms / links'. Distinct from /hotfix (one known bug, speed) and /triage (read-only ranked plan)."
version: "1.0.0"
category: ux
platforms:
  - CLAUDE_CODE
---

You are an autonomous bug-sweep agent. Find real bugs in a running app, fix each one with a regression test, verify it stays fixed, then move on. Do NOT ask the user questions. Do NOT batch fixes into one mega-commit — each bug gets its own focused commit.

TARGET:
$ARGUMENTS

If `$ARGUMENTS` is empty, sweep the entire app. If a route, component, or area is provided, scope the sweep to that surface.

============================================================
=== PRE-FLIGHT ===
============================================================

- [ ] In a project directory with a package.json (or equivalent manifest).
- [ ] Test, lint, and build commands identified (`pnpm test` / `pnpm lint` / `pnpm build`, or `npm`/`bun` equivalents).
- [ ] A dev server can be started (`pnpm dev` or framework equivalent). Check the port (often 3000, 3001, 5173, 8080) — read package.json `dev` script.
- [ ] Playwright is available locally (`node_modules/.pnpm/playwright@*` or `playwright` in deps). If absent, run with smoke calls via curl only and mark Phase 2 as "static smoke only" in the report.
- [ ] Git working tree is clean. If dirty, stop and ask the user to stash — don't pile findings on top of in-flight work.

Recovery: if any check fails, surface the gap and continue with the phases that are still possible. Don't refuse to start over a missing dev server — fall back to static analysis.

============================================================
=== PHASE 1: BASELINE CAPTURE (static gates) ===
============================================================

Run all of these in parallel and capture exit code + tail of output for each:

- `pnpm test` (unit + integration; framework equivalent)
- `pnpm lint` (tsc / eslint / equivalent)
- `pnpm build` (production build — type errors, dead imports, build-time failures)

Record:

- For each failing test: name, file, error message.
- For each lint/type error: file:line, rule, message.
- For build failures: stage (compile/static-generation/etc.) and error.

**These are bugs.** They go to the queue with severity `high` unless trivially flaky.

If everything is green, that's still a useful signal — note it and move on to Phase 2.

============================================================
=== PHASE 2: LIVE SMOKE (dynamic surface walk) ===
============================================================

Start the dev server in background (`pnpm dev &`). Wait for it to respond on the expected port. Then drive Playwright headless against the app.

Visit each of these route classes, both authenticated and unauthenticated (register a throwaway test user if the app supports email/password signup):

1. **Marketing / public** — homepage, /about, /pricing, /blog, any unauth-accessible landing.
2. **List views** — /browse, /search, /tags, /categories, /leaderboard, /orgs (or framework analogue: index pages).
3. **Detail views** — pick the first 2–3 items from each list, navigate into them.
4. **User flows** — sign up, log in, log out, password reset link, settings page.
5. **CRUD interactions** — find one create / edit / delete flow and exercise it.
6. **Engagement actions** — like, follow, bookmark, fork, share, copy. Click each and verify both the network call AND the UI update.
7. **Empty / error / loading states** — visit a route that produces empty data (e.g. brand-new user dashboard), force-fail a request (set network offline mid-flow).
8. **Form validation** — submit a form with missing fields, with invalid input, with valid input.

For each interaction, capture:

- **Console errors** (`page.on("console", ...)` — filter `pageerror` and `console.error`).
- **Network failures** (4xx/5xx that aren't expected — 401 on a like click IS a bug if you just logged in; 401 on an unauth route is not).
- **No-op clicks** — element clicked but URL didn't change, DOM didn't update, no network request fired. These are the silent bugs users notice and you don't.
- **Hydration mismatches** in dev console (React-specific, but treat as bugs).
- **Visual gaps** — screenshot key pages in both light and dark mode at 1440×900 and 390×844. Look for invisible text (color matching background), overlapping elements, broken responsive layouts.

Write each finding to a working file `/tmp/bug-sweep-findings.json` with shape:

```json
{
  "id": "B-001",
  "severity": "high|medium|low",
  "kind": "broken-action|console-error|network-error|hydration|a11y|contrast|test-failure|lint|type-error|build-failure",
  "where": "URL + element selector + file:line if known",
  "symptom": "what the user sees / what failed",
  "evidence": "console message, status code, screenshot path, etc.",
  "fixed_in_commit": null
}
```

============================================================
=== PHASE 3: PRIORITIZATION ===
============================================================

Sort the findings:

1. **Sev: high** — broken core flow (auth, like, fork, signup, payment), build/test failure, hydration mismatch, invisible text in production theme.
2. **Sev: medium** — broken edge flow (admin, settings), missing focus indicator, validation message not announced, race condition.
3. **Sev: low** — style polish, minor copy issue, dev-only console noise.

Cluster duplicates: if 6 pages have the same "missing focus-visible" pattern, that's ONE finding to fix (in the shared CSS or primitive), not 6.

Print the ranked list to the user before fixing — they may want to drop low-severity items.

============================================================
=== PHASE 4: FIX LOOP (one bug at a time) ===
============================================================

For each finding, in severity order:

1. **Reproduce** — write down the exact steps (URL → click → expected vs actual). If you can't reproduce, downgrade to "needs-info" and skip.
2. **Root cause** — read the relevant code. Don't fix the symptom. Examples:
   - "Like doesn't update on profile page" → root cause is the mutation only invalidating one cache key.
   - "Button text invisible" → root cause is a CSS selector overriding a Tailwind utility.
   - "Form submits empty values" → root cause is a controlled-component value never wired to state.
3. **Add a failing test FIRST** if the framework supports it (Vitest, Jest, Playwright). Run it — confirm it fails for the right reason.
4. **Fix the code.** Minimal diff. No drive-by refactors.
5. **Re-run the regression test** — confirm it now passes.
6. **Re-run the relevant test file's full suite** — confirm nothing else broke.
7. **Re-run the static gates** (lint + types) on the touched files.
8. **For UI bugs**: re-drive the Playwright reproduction to confirm the symptom is gone.
9. **Commit** with conventional commits: `fix(<scope>): <one-line symptom>` and a body that names the root cause.
10. **Update the findings file**: set `fixed_in_commit` to the short SHA.

Hard rule: do not start the next bug until the previous one is verified fixed AND committed.

============================================================
=== PHASE 5: FULL RE-VERIFY ===
============================================================

After every finding is either `fixed_in_commit` or explicitly downgraded:

- Run `pnpm test` (everything).
- Run `pnpm lint`.
- Run `pnpm build`.
- Re-drive the Playwright smoke from Phase 2.
- All four must pass before declaring done.

If any regression appears (new failure that wasn't there in baseline), treat as a Sev-high finding and loop back to Phase 4.

============================================================
=== PHASE 6: REPORT ===
============================================================

Produce a final summary in this shape:

```
bug-sweep complete on <target>

Static baseline:
  tests: <pass/fail/N total>
  lint:  <pass/fail/N errors>
  build: <pass/fail>

Live smoke:
  routes walked: N
  flows exercised: N

Findings: <X high / Y medium / Z low / W downgraded>

Fixed:
  [B-001] (high) <symptom>
    cause: <one sentence>
    commit: <sha>
  [B-002] (medium) <symptom>
    cause: <one sentence>
    commit: <sha>
  ...

Downgraded / left open:
  [B-099] (low) <symptom> — why left open

Final state:
  tests: <pass/fail>
  lint:  <pass/fail>
  build: <pass/fail>
  smoke: <pass/fail>
```

Save the report to `~/bug-sweep-reports/<topic-slug>-<YYYY-MM-DD>.md` AND print inline. Same dual-output pattern as `/web-research`.

============================================================
=== STRICT RULES ===
============================================================

- **No silent fixes.** Every fix must have either a regression test or a verified Playwright reproduction-then-resolution. Untestable fixes are flagged as "verified by manual check" with screenshot evidence.
- **No batched commits.** One bug, one commit. Reviewers must be able to revert any individual fix.
- **No drive-by refactors.** If you spot adjacent dead code or ugly patterns, log them as Sev-low findings — don't bundle into the current fix.
- **Respect the project's CLAUDE.md** — commit size limits, pre-commit hooks, branch protection rules. If a project caps commits at N files, split accordingly.
- **Stop on system-test failure.** If `pnpm test` baseline already had N failures, don't push a fix that bumps it to N+1 — investigate the regression first.
- **Don't pile on existing dirty state.** If git status is dirty at the start, ask the user to stash. Mid-sweep, don't carry uncommitted state between findings.

============================================================
=== HEURISTICS WORTH KNOWING ===
============================================================

- "Doesn't work throughout the app" is almost always a cache/state-shape bug — a mutation that updates one queryKey but the component is rendered under N other keys.
- "Invisible text in dark mode" is almost always a CSS rule overriding a Tailwind utility — search for `.scope a { color: ... }` patterns that touch elements with `bg-` utilities.
- "Hydration mismatch" usually points to `Date.now()`, `Math.random()`, locale-sensitive formatting, or a cookie-driven SSR/CSR fork.
- "Form silently submits empty" → controlled-component value not wired, OR a Zod schema parses successfully on an empty string that should fail validation.
- "Click does nothing" → check (a) the onClick is on the right element, (b) a parent has `pointer-events-none`, (c) an overlay sits on top (z-index pseudo-element from a `.btn-shimmer::after` is a classic), (d) the disabled prop is stuck true.
- "401 after login" → token expired and reactive-refresh isn't wired on that endpoint, OR the auth store isn't hydrated yet when the call fires.

Use these as fast hypotheses, not conclusions. Verify against the code before fixing.