Bug Fix

---
name: bug-fix
description: Bug-fixing workflow that coordinates diagnosis, test-driven reproduction, root-cause analysis, and targeted fixes. Use when the user wants to fix a bug with thorough investigation and regression testing.
model: opus
---

# Bugfix - Automated Bug-Fixing Workflow

Coordinates specialist agents through a bug-fixing cycle: clarify bug -> reproduce with failing test -> diagnose root cause -> implement fix -> verify -> review -> document.

## Workflow

### 1. Clarify the bug

**Gather bug details from user:**
- What are the symptoms? (error messages, unexpected behavior, crashes)
- What is the expected behavior vs actual behavior?
- How do you reproduce it? (steps, inputs, configuration)
- When did it start? Any recent changes that might be related?
- Environment specifics? (OS, versions, configuration)

**Ask clarifying questions if needed:**
- Ambiguous symptoms
- Missing reproduction steps
- Unclear expected behavior

Loop back to user until the bug is clearly understood. You need enough information to write a test that demonstrates the failure.

### 2. Write Failing Test(s)

**Detect project language/framework:**
- Check for language-specific files (go.mod, package.json, Cargo.toml, Dockerfile, Makefile, etc.)
- Determine which specialist agent to use

**Spawn appropriate SME agent:**
- If Golang project: spawn `swe-sme-golang` agent
- If GraphQL schema/resolvers: spawn `swe-sme-graphql` agent
- If Dockerfile changes: spawn `swe-sme-docker` agent
- If Makefile changes: spawn `swe-sme-makefile` agent
- If Ansible playbooks/roles: spawn `swe-sme-ansible` agent
- If Zig project: spawn `swe-sme-zig` agent
- If TypeScript project: spawn `swe-sme-typescript` agent
- If JavaScript project: spawn `swe-sme-javascript` agent
- If HTML/markup changes: spawn `swe-sme-html` agent
- If CSS/styling changes: spawn `swe-sme-css` agent
- Otherwise: write tests directly with general best practices

**SME agent task:**
- Write test(s) that reproduce the reported bug
- Tests should encode the *expected* behavior (so they fail against the *current* buggy behavior)
- Run the tests and **verify they actually fail**
- If the tests pass (bug cannot be reproduced): report back with findings — the bug may be environmental, already fixed, or misunderstood

**This is the contract.** When these tests pass, the bug is fixed.

**If reproduction fails:**
- Return to step 1 for more information from the user
- Report what was tried and why reproduction failed
- Max 2 reproduction attempts before escalating to user with findings

### 3. Diagnosis

**Spawn `swe-bug-investigator` agent:**
- Pass: bug description, failing test(s) from step 2, reproduction results
- Agent performs root-cause analysis:
  - Traces execution paths through the code
  - Git archaeology at agent's discretion (shallow for obvious bugs, deep for systemic ones)
  - Identifies the root cause with supporting evidence
  - Identifies related failure modes that may share the same root cause
- Agent produces a structured diagnosis report

**Diagnosis report includes:**
- Root cause (immediate and underlying)
- Evidence (code paths, git history, test results)
- Recommended fix approach
- Related failure modes (specific, actionable — not vague possibilities)
- Confidence level

### 4. Implement the Fix

**Re-invoke the same SME agent from step 2:**
- Pass the diagnosis report as guidance
- SME implements the fix following the diagnostician's recommended approach
- SME writes additional tests for related failure modes identified in step 3
- SME verifies: the originally-failing test(s) from step 2 now pass
- SME runs the full test suite to check for regressions

**Implementation agent responsibilities:**
- Fix the bug as narrowly and precisely as possible
- Don't refactor unrelated code (that's a separate workflow)
- Write tests for each related failure mode the diagnostician identified
- Ensure all new and existing tests pass

### 5. Quality Assurance - Verify Fix (CRITICAL GATE)

**Spawn `qa-engineer` agent:**
- Pass: original bug description, reproduction steps, and acceptance criteria (the bug should no longer occur)
- The agent infers its mode from context: presence of acceptance criteria triggers acceptance verification
- Agent performs **practical verification first** — actually reproducing the originally-reported scenario and confirming it's fixed
- This means: executing CLI commands, spawning subagents to test MCP tools, making API calls, etc.
- Only AFTER practical verification confirms the fix works does the agent run the full test suite
- Agent also checks the related failure modes identified by the diagnostician

**Practical verification by feature type:**
- CLI tools: Run commands in subshell (skip destructive operations)
- MCP servers/Claude skills: Spawn subagent to actually use the feature
- API integrations: Make actual calls (with caution for dangerous operations)
- Libraries: Quick sanity checks, then unit tests

**This is a CRITICAL GATE:**
- The originally-reported bug must be demonstrably fixed (practical test) AND tests must pass to proceed
- If practical verification fails: return to step 4 (implementation) immediately
- If verification passes but tests fail: debug tests, not implementation
- Track iteration count (max 3 attempts before escalating to user)

**Expected output:** Practical verification results, pass/fail determination with specific findings.

### 6. Code Review (Conditional)

**Only proceed to code review if fix verification passed.** Don't review broken code.

Conditionally invoke specialized reviewers based on code changes and complexity. All reviewers provide feedback; implementation agent responds to all feedback in step 7.

#### 6a. Security Review (Conditional - Has Authority)

**If security-sensitive code changed (auth, crypto, input validation, data access):**

**Spawn `sec-blue-teamer` agent:**
- Evaluates defensive security posture of changed code
- Checks control consistency, defense-in-depth, and configuration
- Identifies systemic gaps that enable vulnerability classes
- **Has authority to demand changes** - security issues should block or require explicit user approval

**Output**: Defense evaluation with severity levels (critical/high/low)

#### 6b. Refactoring Review (Conditional - Advisory)

**If non-trivial implementation (>50 lines changed, multiple files, or complex logic):**

**Spawn `swe-code-reviewer` agent:**
- Reviews implementation for code quality issues
- Identifies refactoring opportunities (DRY violations, dead code, complexity, etc.)
- Provides structured recommendations organized by priority
- Agent will report "No refactoring needed" if code is already clean

**Output**: Refactoring recommendations (advisory only)

#### 6c. Performance Review (Conditional - Advisory)

**If performance-critical code changed (hot paths, loops, database queries, API endpoints):**

**Spawn `swe-perf-reviewer` agent:**
- Reviews code for performance bottlenecks
- Identifies missing benchmarks and profiling gaps
- Provides optimization recommendations

**Output**: Performance metrics and recommendations (advisory only)

### 7. Implement Review Feedback

**Aggregate all review feedback from step 6 and provide to implementation agent.**

**If specialist was used in steps 2/4 (swe-sme-golang, swe-sme-graphql, etc.):**
- Re-invoke the same specialist agent
- Provide all review feedback (security, refactoring, performance)
- Specialist reviews all feedback and **uses own discretion** to implement
- **Security findings**: Must address or get explicit user approval to skip
- **Other feedback**: Advisory only - specialist has final authority
- Specialist may decline recommendations that conflict with language idioms
- Specialist implements accepted changes and commits

**If no specialist (general implementation):**
- Re-invoke the same agent that did implementation in step 4
- Provide all review feedback
- Agent addresses security issues and implements accepted recommendations
- Agent commits changes

**Note**: Security issues have authority to block; other feedback is advisory. Implementation agent makes final decisions on advisory feedback.

### 8. SME Peer Review (Conditional)

**Condition:** Non-trivial changes (>50 lines changed, multiple files, or complex logic).

**Skip if:**
- Changes are trivial (single file, <50 lines, simple logic)
- No language-specific SME was used in step 2 (general implementation)

**If applicable, spawn a fresh instance of the same SME type used in step 2:**
- Fresh context window - reviewer sees only current code state via git diff
- Reviews with "would I accept this PR" lens
- Focuses on: minor oversights, idiomatic patterns, naming, small cleanups
- **Has authority to make small fixes directly**

**Scope constraints (critical):**
- Small cleanups and nits only
- No architectural changes
- No re-implementing features
- No changing approaches or patterns chosen by original SME
- If something seems wrong at a deeper level, flag it rather than fix it

**Expected output:** Small fixes committed, or "no changes needed" if code is clean.

### 9. Quality Assurance - Coverage & Quality Verification

**Spawn `qa-engineer` agent:**
- The agent infers its mode from context: absence of acceptance criteria triggers general assessment
- Agent performs general QA assessment of all changed code (from steps 4, 7, and 8)
- Assess test coverage for new/modified code
- Identify gaps and write missing tests
- Run linters/formatters and fix issues
- Evaluate test quality (assertions, edge cases)
- **Verify implementations from steps 7 and 8 didn't break tests** - catches issues from refactoring, security fixes, or peer review cleanups

**This is SUPPLEMENTARY:**
- Issues found here don't block the workflow by default
- Agent documents issues and proposes fixes
- Minor issues: proceed to documentation
- Significant issues (tests broken, major bugs): return to step 7 (review feedback) or step 4 (implementation)

**Expected output:** Coverage metrics, tests added/modified, quality issues found, confirmation that all changes still pass tests.

### Feedback Loops

**Reproduction failure (step 2):**
- Return to step 1 (clarification)
- Report what was tried and why reproduction failed
- Max 2 reproduction attempts before escalating to user

**Fix verification failure (step 5):**
- Return to step 4 (implementation)
- Track iteration count (max 3 attempts before escalating to user)
- Report specific failures (which tests still fail, what practical verification showed)

**Security review findings (step 6a):**
- Critical/High severity: Must address in step 7 or get explicit user approval to skip
- Medium/Low severity: Advisory - implementation agent decides in step 7

**Code review feedback (steps 6b-6c):**
- All refactoring and performance feedback is advisory
- Implementation agent in step 7 uses discretion to implement

**Peer review issues (step 8):**
- If peer review changes break tests: revert peer review changes and proceed (nits aren't worth breaking functionality)
- If peer review flags deeper issues: escalate to user for decision

**Coverage & quality issues (step 9):**
- Tests broken by changes from step 7: Return to step 7 to fix or revert
- Tests broken by changes from step 8: Revert step 8 changes (peer review nits shouldn't break tests)
- Major bugs found: Return to step 4 (implementation)
- Minor issues (low coverage in non-critical code, style nitpicks): document and proceed
- User can approve proceeding despite issues if acceptable

### 10. Documentation

**Spawn `doc-maintainer` agent:**
- Review git diff to identify which files/modules changed
- Determine which documentation is affected:
  - README.md if user-facing functionality changed
  - CLAUDE.md if architecture/integration points changed
  - API docs if public interfaces changed
  - Internal docs (doc/, adr/) if implementation details relevant to architecture changed
- Focus review on documentation related to changed code
- Verify code examples in affected docs still work
- Check for broken links in modified documentation

**Agent should be targeted, not comprehensive:**
- Only review documentation relevant to the changes made
- Skip full codebase documentation scan
- Report "no documentation changes needed" if changes are purely internal with no doc impact

### 11. Final verification

**Run comprehensive checks:**
- Execute full test suite (must pass)
- Run all linters and formatters
- Verify no new warnings introduced
- Check git status (document any uncommitted changes)

**Present summary to user:**
- Bug that was fixed (original report)
- Root cause identified (from diagnosis)
- Files changed
- Tests added/modified (regression tests for the bug + related failure modes)
- Any remaining TODOs or follow-ups

**If verification fails:**
- Determine root cause (implementation bug vs. refactoring issue vs. test issue)
- Return to appropriate step (step 4 for implementation bugs, step 7 for refactoring issues)
- Report specific failures to user

### 12. Workflow Completion (Optional)

**After presenting summary from step 11, ask user if they want to complete the workflow.**

User may also explicitly request workflow completion at any point after step 11 succeeds.

**If user confirms, perform housekeeping tasks:**

#### 12a. Commit Changes

**If uncommitted changes exist:**
- Review git status to see what changed
- Create commit with descriptive message
- If ticket number is known (from branch name, prior context, or user input):
  - Reference ticket in commit message (e.g., "Fixes #123" or "Closes: #123")
- Use heredoc format for multi-line commit messages

**Example commit message format:**
```
Fix off-by-one error in pagination boundary check

Root cause: boundary comparison used < instead of <= when calculating
the last page, causing the final item to be excluded from results.
Also added regression tests for adjacent edge cases identified during
diagnosis.

Fixes #456
```

#### 12b. Update/Close Issue Tracker Ticket (Conditional)

Detect tracker, recover the ticket number, and post the close-out per [`references/trackers.md`](../../references/trackers.md) (Detection Procedure + "Comment / update (close-out)" + "Close" operations).

**Close-out comment content (skill-specific):**
- Root cause identified
- Fix applied
- Tests added (regression + related failure modes)
- Files changed

#### 12c. Sync with Main Branch (Conditional)

**Check branch state:**
- Identify main branch name (master or main)
- Check if current branch is not main
- Check if there are new commits on main that current branch doesn't have

**If current branch is behind main:**
- Ask user: "Your branch is behind main. Would you like to rebase on main?"
- If user confirms:
  - Perform: `git fetch origin main && git rebase origin/main`
  - If conflicts arise, report to user and halt (don't auto-resolve)
  - If rebase succeeds, report success

**Skip if:**
- Current branch is main/master
- Current branch is up to date with main
- No main/master branch exists

**Present final status:**
- Changes committed
- Ticket updated/closed
- Branch rebased on main
- Ready to push or move to next task

## Agent Coordination

**Sequential execution:**
- Agents run one at a time (no parallel spawning)
- Each agent completes before next begins
- Use Task tool to spawn agents

**State management:**
- Track current workflow step
- Track reproduction attempt count (for step 2 failures)
- Track QA iteration count (for fix verification failures)
- Accumulate summary information
- Preserve original bug report for passing to QA verification
- Preserve diagnosis report for passing to implementation agent

**Agent self-skipping:**
- Agents should skip work if not applicable
- Report "nothing to do" rather than making unnecessary changes

**SME continuity:**
- The same SME type is used across steps 2 (failing test), 4 (fix), 7 (review feedback), and 8 (peer review)
- Steps 2 and 4 should ideally be the same instance or carry forward context
- Step 8 (peer review) must be a fresh instance for independent perspective

**Diagnosis pass-through:**
- The diagnostician's report from step 3 is passed to the SME in step 4
- The SME should acknowledge the diagnosis and follow its recommended approach
- The SME should write tests for each related failure mode the diagnostician identified

## Iteration Limits

**Maximum iterations:**
- Reproduction loop (step 2): 2 attempts, then escalate to user
- Fix verification loop (step 5): 3 attempts, then escalate to user
- Overall workflow: 12 total agent spawns (safety limit)

**Escalation to user:**
- Present current state
- Explain what's blocking progress
- Request guidance