bug-fix

What this skill does

# 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