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:

Local files: Look for bugs.md, BUGS.md, TODO.md, todo.md, ISSUES.md, or similar in the repo root and docs/ directory
GitHub Issues: Run gh issue list --state open --limit 100 to check for a GitHub-based tracker
Project instructions: Read CLAUDE.md, CONTRIBUTING.md, README.md for pointers to where bugs are tracked
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

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

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).
Run the build: Execute the build command. If it fails, STOP — tell the user the baseline is broken and list the failures.
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

Read the bug description carefully. Identify:

What is the expected behavior?
What is the actual (broken) behavior?
What files/modules are likely involved?

Use Grep, Glob, and Read tools to find the relevant code. Understand the current implementation before changing anything.

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)

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. Follow these principles:

Minimal change: Fix the bug, don't refactor the neighborhood. Keep the diff small.
Match existing patterns: Follow the codebase's conventions for style, naming, and error handling.
No drive-by changes: Don't fix unrelated issues in the same commit. If you spot another bug, add it to the bug tracker — don't fix it inline.

Step 4: Test

Verify the fix thoroughly:

Confirm the failing test now passes (or the interactive repro no longer reproduces)
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.
Add or update tests for the fixed behavior if a test didn't already exist
Interactive/E2E testing if the project supports it (especially for UI bugs):
- For TUI apps: build, launch in tmux, interact, capture pane output
- For web apps: start the server, curl endpoints or check browser
- For CLI tools: run with various inputs and check output
- For libraries: ensure the public API still works as documented

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)

Phase 3: Skipping Bugs

Skip a bug and move on if any of these apply:

Ambiguous requirements: The bug description is unclear and multiple interpretations lead to different fixes. Log: "Skipped — ambiguous requirements. Needs clarification on [specific question]."
Too large: The fix would require a major refactor or architectural change. Log: "Skipped — fix requires [description of scope]. Not suitable for a bug bash."
Conflicting requirements: The fix would break another documented behavior or contradict another bug's resolution. Log: "Skipped — conflicts with [other bug/requirement]."
Cannot reproduce: The bug doesn't manifest in the current code or your environment. Log: "Skipped — could not reproduce as of [commit hash]."
Dangerous: The fix touches security-critical code, data migration, or deployment infrastructure in ways that need human review. Log: "Skipped — needs human review for [reason]."
Blocked: The fix depends on another bug being fixed first. Log: "Skipped — blocked by [other bug]. Fix that one first."

Always log the reason in the bug tracker entry. Never silently skip.

Phase 4: Session Summary

After all bugs are processed (or the limit is reached), produce a summary:

# Bug Bash Summary

**Date**: [date]
**Scope**: [all / P0-P1 / max 5 / etc.]
**Baseline**: [commit hash at start]

## Results

| # | Priority | Bug | Result | Commit |
|---|----------|-----|--------|--------|
| 1 | P1 | Shell injection in Git.pm | FIXED | abc1234 |
| 2 | P1 | Stale TODO.md references | FIXED | def5678 |
| 3 | P2 | Shift+Tab broken in palette | FIXED | ghi9012 |
| 4 | P2 | God object decomposition | SKIPPED | — |
| 5 | P3 | Junk files not gitignored | FIXED | jkl3456 |

**Fixed**: 4 | **Skipped**: 1 | **Regressed**: 0

## Skipped Bugs
- **P2: God object decomposition** — Too large. Fix requires architectural refactor across Editor.pm, Commands.pm, and Palette.pm. Not suitable for a bug bash.

## Decisions Made
- [Any judgment calls you made during the bash, with reasoning]

## Test Suite Status
- Baseline: 927 tests, 926 passed, 1 pre-existing failure (syntax_samples.t)
- Final: 934 tests, 933 passed, 1 pre-existing failure (syntax_samples.t)
- New tests added: 7

Push the branch if on a feature branch. Report the summary to the user.

Decision-Making Guidelines

You are working unassisted. When a decision is required:

Prefer the conservative option. If unsure between two approaches, pick the one that changes less code and has less risk.
Follow existing patterns. If the codebase does X one way everywhere, do it the same way — even if you think another way is better.
Don't gold-plate. Fix the bug as described. Don't add features, extra configurability, or "while I'm here" improvements.
When in doubt, skip. It's better to skip a bug and let a human decide than to make a bad fix that introduces a regression.
Log everything. Every decision, every skip reason, every judgment call goes in the bug tracker and commit message. A human will review your work later.

Important Safety Rules

Never force-push. Always use regular git push.
Never modify git config. Don't change user.name, user.email, or any git settings.
One commit per bug. Don't squash or amend across bugs.
Revert on regression. If your fix breaks something, revert it — don't try to fix the fix.
Respect pre-commit hooks. If a hook fails, fix the issue and create a new commit (don't --no-verify).
Don't delete test files. Even if they seem broken or outdated.
Don't touch CI/CD config unless a bug specifically calls for it.