Fix Bug

Diagnose and fix a bug in an existing project.

Input

$ARGUMENTS

Expected formats:

• •Bug description: /fix-bug "Login button does nothing when clicked" --repo my-app
• •GitHub issue number: /fix-bug #42 --repo my-app
• •GitHub issue URL: /fix-bug https://github.com/user/repo/issues/42
• •In current directory: /fix-bug "API returns 500 on empty input"

Workflow

Step 1: Locate the Project

• •If --repo <name> points to projects/<name>/, use that directory
• •If --repo <github-url> or issue URL contains a repo, clone into projects/ if not already present
• •If no --repo, use the current working directory
• •Ensure a git remote exists and the repo is on GitHub

Step 2: Gather Bug Context

If given a GitHub issue number or URL:

gh issue view <N> --json title,body,labels,comments

Extract the bug description, reproduction steps, expected vs actual behavior.

If given a text description:

• •Use the description as-is for investigation

In both cases, also check:

• •Recent commits for related changes: git log --oneline -20
• •Open issues for duplicates: gh issue list --state open --json number,title

Step 3: Investigate Root Cause

1. •

   Search for relevant code — Use the bug description to identify keywords, error messages, or component names. Search the codebase:

   • •Grep for error messages, function names, or component names mentioned in the bug
   • •Read related files to understand the code flow
   • •Check test files for existing coverage of the buggy behavior
2. •

   Trace the code path — Follow the execution flow from user action to the point of failure:

   • •Identify the entry point (route, handler, component, CLI command)
   • •Trace through function calls, state changes, and data flow
   • •Identify where the behavior diverges from expectations
3. •

   Identify the root cause — Determine what is wrong:

   • •Off-by-one errors, null/undefined checks, wrong conditionals
   • •Missing error handling, race conditions, stale state
   • •Incorrect API usage, wrong data format, missing validation
   • •Dependency issues, configuration errors
4. •

   Document findings — Before making changes, summarize:

   • •Root cause in one sentence
   • •Which files and functions are affected
   • •Why the current code produces the wrong behavior

Step 4: Ensure Staging Branch Exists

git branch -r --list origin/staging

If staging doesn't exist, create it from main:

git checkout main && git pull origin main
git checkout -b staging && git push -u origin staging

Step 5: Create a GitHub Issue (if one doesn't exist)

If the bug was provided as a text description (not an issue number), create one:

gh issue create --title "Bug: <short description>" --body "<formatted body per CLAUDE.md template>"

Label it with bug. Record the issue number.

Step 6: Create Fix Branch

git checkout staging
git pull origin staging
git checkout -b fix/issue-<N>-<slug>

Where <slug> is the bug title lowercased, non-alphanumeric chars replaced by hyphens, max 50 chars. Use fix/ prefix instead of feature/ for bug fixes.

Step 7: Implement the Fix

1. •Make the minimal change that fixes the root cause. Do not refactor surrounding code.
2. •Add or update tests to cover the bug:
   • •Add a test that reproduces the bug (would fail without the fix)
   • •Ensure existing tests still pass
3. •Verify the fix — Run the relevant test suite to confirm:
   • •The new test passes
   • •No existing tests are broken

Step 8: Commit and Push

git add <specific-files>
git commit -m "Fix: <bug-description>

Closes #<issue-number>"
git push -u origin fix/issue-<N>-<slug>

Step 9: Create Pull Request

Generate a PR description with:

• •Summary: What the bug was, what caused it, and how it's fixed
• •Root Cause: Technical explanation of why the bug occurred
• •Changes: What was changed and why
• •Test Plan: How to verify the fix (with - [ ] checkboxes)

gh pr create --base staging --head fix/issue-<N>-<slug> \
  --title "Fix: <bug-description>" \
  --body "Fixes #<issue-number>

<generated PR description>"

Step 10: Review and Merge

1. •Delegate to reviewer agent for code review
2. •Delegate to tester agent to execute the test plan
3. •Squash-merge the PR:
   bash

   gh pr merge <pr-number> --squash --delete-branch
   

4. •Close the issue if not auto-closed:
   bash

   gh issue close <issue-number> --comment "Fixed via PR #<pr-number>"
   

Step 11: Merge to Main

After the fix is merged to staging:

gh pr create --base main --head staging \
  --title "Bugfix: <bug-description>" \
  --body "<summary of the fix>"
gh pr merge <pr-number> --merge
git checkout main && git pull origin main
git checkout staging && git pull origin staging

Output

Report:

• •Root cause summary
• •Files changed
• •PR number and URL
• •Test results

Example Usage

# Fix a bug described in text
/fix-bug "Users can submit empty forms" --repo my-app

# Fix a bug from a GitHub issue
/fix-bug #42 --repo my-app

# Fix a bug using a GitHub issue URL
/fix-bug https://github.com/user/repo/issues/42

# Fix a bug in the current project directory
/fix-bug "API crashes when date field is null"