| name | bug-bash |
| description | Work through a project's bug list autonomously, fixing bugs in priority order |
| argument-hint | ["P0-P1 | --max N | --dry-run"] |
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:
- 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.
