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-