/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