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 ===
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):
- Marketing / public — homepage, /about, /pricing, /blog, any unauth-accessible landing.
- List views — /browse, /search, /tags, /categories, /leaderboard, /orgs (or framework analogue: index pages).
- Detail views — pick the first 2–3 items from each list, navigate into them.
- User flows — sign up, log in, log out, password reset link, settings page.
- CRUD interactions — find one create / edit / delete flow and exercise it.
- Engagement actions — like, follow, bookmark, fork, share, copy. Click each and verify both the network call AND the UI update.
- 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).
- 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:
{
"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:
- Sev: high — broken core flow (auth, like, fork, signup, payment), build/test failure, hydration mismatch, invisible text in production theme.
- Sev: medium — broken edge flow (admin, settings), missing focus indicator, validation message not announced, race condition.
- 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:
- Reproduce — write down the exact steps (URL → click → expected vs actual). If you can't reproduce, downgrade to "needs-info" and skip.
- 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.
- Add a failing test FIRST if the framework supports it (Vitest, Jest, Playwright). Run it — confirm it fails for the right reason.
- Fix the code. Minimal diff. No drive-by refactors.
- Re-run the regression test — confirm it now passes.
- Re-run the relevant test file's full suite — confirm nothing else broke.
- Re-run the static gates (lint + types) on the touched files.
- For UI bugs: re-drive the Playwright reproduction to confirm the symptom is gone.
- Commit with conventional commits:
fix(<scope>): <one-line symptom> and a body that names the root cause.
- 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.
1---2name: bug-sweep3description: "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)."4version: "1.0.0"5category: ux6platforms:7 - CLAUDE_CODE8metadata:9 source: https://skillmd.com/skills/tinh2/bug-sweep10---1112You 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.1314TARGET:15$ARGUMENTS1617If `$ARGUMENTS` is empty, sweep the entire app. If a route, component, or area is provided, scope the sweep to that surface.1819============================================================20=== PRE-FLIGHT ===21============================================================2223- [ ] In a project directory with a package.json (or equivalent manifest).24- [ ] Test, lint, and build commands identified (`pnpm test` / `pnpm lint` / `pnpm build`, or `npm`/`bun` equivalents).25- [ ] A dev server can be started (`pnpm dev` or framework equivalent). Check the port (often 3000, 3001, 5173, 8080) — read package.json `dev` script.26- [ ] 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.27- [ ] Git working tree is clean. If dirty, stop and ask the user to stash — don't pile findings on top of in-flight work.2829Recovery: 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.3031============================================================32=== PHASE 1: BASELINE CAPTURE (static gates) ===33============================================================3435Run all of these in parallel and capture exit code + tail of output for each:3637- `pnpm test` (unit + integration; framework equivalent)38- `pnpm lint` (tsc / eslint / equivalent)39- `pnpm build` (production build — type errors, dead imports, build-time failures)4041Record:4243- For each failing test: name, file, error message.44- For each lint/type error: file:line, rule, message.45- For build failures: stage (compile/static-generation/etc.) and error.4647**These are bugs.** They go to the queue with severity `high` unless trivially flaky.4849If everything is green, that's still a useful signal — note it and move on to Phase 2.5051============================================================52=== PHASE 2: LIVE SMOKE (dynamic surface walk) ===53============================================================5455Start the dev server in background (`pnpm dev &`). Wait for it to respond on the expected port. Then drive Playwright headless against the app.5657Visit each of these route classes, both authenticated and unauthenticated (register a throwaway test user if the app supports email/password signup):58591. **Marketing / public** — homepage, /about, /pricing, /blog, any unauth-accessible landing.602. **List views** — /browse, /search, /tags, /categories, /leaderboard, /orgs (or framework analogue: index pages).613. **Detail views** — pick the first 2–3 items from each list, navigate into them.624. **User flows** — sign up, log in, log out, password reset link, settings page.635. **CRUD interactions** — find one create / edit / delete flow and exercise it.646. **Engagement actions** — like, follow, bookmark, fork, share, copy. Click each and verify both the network call AND the UI update.657. **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).668. **Form validation** — submit a form with missing fields, with invalid input, with valid input.6768For each interaction, capture:6970- **Console errors** (`page.on("console", ...)` — filter `pageerror` and `console.error`).71- **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).72- **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.73- **Hydration mismatches** in dev console (React-specific, but treat as bugs).74- **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.7576Write each finding to a working file `/tmp/bug-sweep-findings.json` with shape:7778```json79{80 "id": "B-001",81 "severity": "high|medium|low",82 "kind": "broken-action|console-error|network-error|hydration|a11y|contrast|test-failure|lint|type-error|build-failure",83 "where": "URL + element selector + file:line if known",84 "symptom": "what the user sees / what failed",85 "evidence": "console message, status code, screenshot path, etc.",86 "fixed_in_commit": null87}88```8990============================================================91=== PHASE 3: PRIORITIZATION ===92============================================================9394Sort the findings:95961. **Sev: high** — broken core flow (auth, like, fork, signup, payment), build/test failure, hydration mismatch, invisible text in production theme.972. **Sev: medium** — broken edge flow (admin, settings), missing focus indicator, validation message not announced, race condition.983. **Sev: low** — style polish, minor copy issue, dev-only console noise.99100Cluster 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.101102Print the ranked list to the user before fixing — they may want to drop low-severity items.103104============================================================105=== PHASE 4: FIX LOOP (one bug at a time) ===106============================================================107108For each finding, in severity order:1091101. **Reproduce** — write down the exact steps (URL → click → expected vs actual). If you can't reproduce, downgrade to "needs-info" and skip.1112. **Root cause** — read the relevant code. Don't fix the symptom. Examples:112 - "Like doesn't update on profile page" → root cause is the mutation only invalidating one cache key.113 - "Button text invisible" → root cause is a CSS selector overriding a Tailwind utility.114 - "Form submits empty values" → root cause is a controlled-component value never wired to state.1153. **Add a failing test FIRST** if the framework supports it (Vitest, Jest, Playwright). Run it — confirm it fails for the right reason.1164. **Fix the code.** Minimal diff. No drive-by refactors.1175. **Re-run the regression test** — confirm it now passes.1186. **Re-run the relevant test file's full suite** — confirm nothing else broke.1197. **Re-run the static gates** (lint + types) on the touched files.1208. **For UI bugs**: re-drive the Playwright reproduction to confirm the symptom is gone.1219. **Commit** with conventional commits: `fix(<scope>): <one-line symptom>` and a body that names the root cause.12210. **Update the findings file**: set `fixed_in_commit` to the short SHA.123124Hard rule: do not start the next bug until the previous one is verified fixed AND committed.125126============================================================127=== PHASE 5: FULL RE-VERIFY ===128============================================================129130After every finding is either `fixed_in_commit` or explicitly downgraded:131132- Run `pnpm test` (everything).133- Run `pnpm lint`.134- Run `pnpm build`.135- Re-drive the Playwright smoke from Phase 2.136- All four must pass before declaring done.137138If any regression appears (new failure that wasn't there in baseline), treat as a Sev-high finding and loop back to Phase 4.139140============================================================141=== PHASE 6: REPORT ===142============================================================143144Produce a final summary in this shape:145146```147bug-sweep complete on <target>148149Static baseline:150 tests: <pass/fail/N total>151 lint: <pass/fail/N errors>152 build: <pass/fail>153154Live smoke:155 routes walked: N156 flows exercised: N157158Findings: <X high / Y medium / Z low / W downgraded>159160Fixed:161 [B-001] (high) <symptom>162 cause: <one sentence>163 commit: <sha>164 [B-002] (medium) <symptom>165 cause: <one sentence>166 commit: <sha>167 ...168169Downgraded / left open:170 [B-099] (low) <symptom> — why left open171172Final state:173 tests: <pass/fail>174 lint: <pass/fail>175 build: <pass/fail>176 smoke: <pass/fail>177```178179Save the report to `~/bug-sweep-reports/<topic-slug>-<YYYY-MM-DD>.md` AND print inline. Same dual-output pattern as `/web-research`.180181============================================================182=== STRICT RULES ===183============================================================184185- **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.186- **No batched commits.** One bug, one commit. Reviewers must be able to revert any individual fix.187- **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.188- **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.189- **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.190- **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.191192============================================================193=== HEURISTICS WORTH KNOWING ===194============================================================195196- "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.197- "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.198- "Hydration mismatch" usually points to `Date.now()`, `Math.random()`, locale-sensitive formatting, or a cookie-driven SSR/CSR fork.199- "Form silently submits empty" → controlled-component value not wired, OR a Zod schema parses successfully on an empty string that should fail validation.200- "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.201- "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.202203Use these as fast hypotheses, not conclusions. Verify against the code before fixing.