bug-bash

Files (1)

• SKILL.md

SKILL.md (first lines)

# Bug Bash

Autonomously work through a project's bug/issue list, fixing bugs in priority order. Reproduce each bug, fix it, test it, commit it, and move on — without waiting for human input.

## When to Use

- Clearing a backlog of known bugs
- Hardening before a release
- Focused cleanup sprint

## How to Invoke

```
/bug-bash                     # Fix all bugs, highest priority first
/bug-bash P0-P1               # Only fix P0 and P1 (or critical/high) bugs
/bug-bash --max 5             # Fix at most 5 bugs, then stop
/bug-bash --dry-run           # Triage only — report what you'd fix, don't change code
```

---

## Phase 0: Discover the Bug List

Find the project's bug/issue tracker. Check these sources in order:

1. **Local files**: Look for `bugs.md`, `BUGS.md`, `TODO.md`, `todo.md`, `ISSUES.md`, or similar in the repo root and `docs/` directory
2. **GitHub Issues**: Run `gh issue list --state open --limit 100` to check for a GitHub-based tracker
3. **Project instructions**: Read `CLAUDE.md`, `CONTRIBUTING.md`, `README.md` for pointers to where bugs are tracked
4. **Inline markers**: `grep -r "TODO\|FIXME\|HACK\|BUG\|XXX" --include="*.{py,js,ts,rb,go,rs,java,pm,pl}" -l` as a last resort

If no bug list is found, tell the user and stop.

Once found, read the entire bug list. Parse out:
- Each bug's **priority** (P0/P1/P2/P3, critical/high/medium/low, or whatever scheme the project uses)
- Each bug's **status** (open, fixed, won't-fix, etc.)
- Each bug's **description**

Filter to open bugs only. Sort by priority (highest first), then by order of appearance. If the user specified a priority range or max count, apply those filters.

---

## Phase 1: Pre-flight Check

**Work in your own worktree, never the shared checkout.** `git worktree add <path> -b bug-bash/<date> main` and do everything there. Other agents may be working the same repo; the shared checkout is touched only to merge. Never `git stash` — `refs/stash` is shared across every worktree of a repo, and a sibling's `stash pop` can cross-apply into yours. And never edit another project's repository: if a bug's fix belongs in a dependency, file it with `/request` and mark this one blocked.

Before touching any code, verify the project builds and tests pass in its current state.

1. **Identify build/test commands**: Read `Makefile`, `package.json`, `Cargo.toml`, `pyproject.toml`, `build.gradle`, etc. Look for the project's documented build and test commands (often in README, CONTRIBUTING, or CLAUDE.md).
2. **Run the build**: Execute the build command. If it fails, STOP — tell the user the baseline is broken and list the failures.
3. **Run the test suite**: Execute the test command. Record the results as the **baseline**.
   - If tests fail, note which ones. These are **pre-existing failures** — do not count them against your fixes later.
   - Record the exact test output for comparison after each fix.

If there is no build system or test suite, note this and proceed with extra caution — you'll rely on interactive testing and code review.

---

## Phase 2: Work Through Bugs

For each bug, in priority order:

### Step 1: Understand

Establish expected versus actual behaviour and the code involved. Understand the current implementation before changing it.

### Step 2: Reproduce

Before writing any fix, confirm the bug exists:
- **Write a failing test** that demonstrates the bug, OR
- **Reproduce interactively** if it's a UI/behavioral issue (use tmux for TUI apps, curl for APIs, etc.), OR
- **Read the code and confirm** the logical error if the bug is evident from inspection (e.g., wrong variable name, off-by-one)

**Proof of bite.** A test that demonstrates the bug must actually fail against the unfixed code — run it *before* the fix and keep the failure output for the commit message. A guard that was never seen to fail is decoration: several have shipped that would have passed either way. If you prove it by tampering (reverting the fix, swapping in the old file), **commit the fix first** — an agent lost all its work to `git checkout --` mid-tamper — and the tampered build must compile and run, or you've proven nothing. Also write the case that must *not* trigger: a predicate tested only on the input its author wrote is unproven.

If you cannot reproduce the bug or confirm it exists in the current code:
- It may already be fixed. Check recent commits.
- It may be environment-specific. Note this.
- Mark as "Could not reproduce" in the bug tracker and move on.

### Step 3: Fix

Implement the fix:
- **One thesis per fix.** Fix the cause, not the symptom — a fix that only adds a guard should say in its commit body why the case was genuinely missing. Don't refactor the neighbourhood unless the fix requires it; if it does, the commit says so. Size isn't the measure; whether it shrinks or holds the learning surface is.
- **Match existing patterns** for style, naming, and error handling.
- **No drive-by changes.** If you spot another bug, add it to the tracker — don't fix it inline.

### Step 4: Test

Verify the fix thoroughly:

1. **Confirm the failing test now passes** (or the interactive repro no longer reproduces)
2. **Run the full test suite**: Compare against the baseline from Phase 1. If any previously-passing test now fails, your fix introduced a regression.
   - If regression: **revert your changes**, note the conflict in the bug tracker ("Fix attempted but caused regression in X — needs more careful approach"), and move on.
3. **Add or update tests** for the fixed behavior if a test didn't already exist
4. **Drive the real thing** if the project has a recipe for it (`CLAUDE.md`'s verification recipe) — especially for UI bugs. Tests exercise the mechanism; this exercises the integration.

### Step 5: Clean Up

While the fix is fresh:
- **Update documentation** if the bug or fix affects documented behavior
- **Update the bug tracker** — mark the bug as fixed with a description of:
  - What the root cause was
  - What the fix was
  - What tests were added
  - Any decisions you made and why

### Step 6: Commit

Create a commit for this bug fix:
- Use a clear commit message referencing the bug (e.g., "Fix P2: Shift+Tab cycles scope backward in find-in-files palette")
- Only include files related to this fix
- Do NOT batch multiple bug fixes into one commit — one bug, one commit

### Step 7: Next Bug

Move to the next bug. Do not wait for human input between bugs. Keep going until:
- All bugs in scope are processed, OR
- The `--max` limit is reached, OR
- You've hit a bug that is unsafe to fix without human guidance (see Phase 3)

From joewalnes/skills, MIT.

More from joewalnes/skills