# bug-fix

Adopt this skill: https://proskills.md/skills/other/chrisallenlane-claude-swe-workflows-skills-bug-fix

Page: https://proskills.md/skills/other/chrisallenlane-claude-swe-workflows-skills-bug-fix
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/bug-fix/SKILL.md
size: 8006
upstream: https://github.com/chrisallenlane/claude-swe-workflows/blob/master/skills/bug-fix/SKILL.md

```text
---
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 
```

## File: README.md
upstream: https://github.com/chrisallenlane/claude-swe-workflows/blob/master/README.md

````text
# claude-swe-workflows

A system of composable software engineering workflows for [Claude Code][cc].
Plan projects, implement tickets, and run quality passes — from a single
ticket to a multi-batch project, using the same layered architecture.

## Installation

```bash
claude plugin marketplace add https://github.com/chrisallenlane/claude-swe-workflows.git
claude plugin install claude-swe-workflows@claude-swe-workflows
```

## Layered Composition

The skills are arranged as **layered composition** — higher-level skills invoke
lower-level ones. Enter at the layer that matches your task. The deepest stack:

```
/lead-project                              ← autonomous tech lead (decides what to do next)
└── invokes any skill below
    /implement-project                     ← full-lifecycle project execution
    └── /implement-batch                   ← one batch of related tickets
        └── /implement                     ← one ticket, end-to-end
            └── SME agents                 ← language-specific specialists
```

Three other entry points orchestrate bounded autonomous loops:

- `/lead-bug-hunt` — loops `/bug-hunt` → `/implement-batch` until bugs converge below a severity floor.
- `/lead-refactor` — `/refactor` → loops `/review-arch` + `/implement-batch` → `/refactor`.
- `/lead-review` — runs every `/review-*` sub-skill once.

Planning feeds implementation: `/scope-project` → `/implement-project`, or
`/scope` → `/implement`. Supporting skills (`/think-*`, `/review-*`, `/bug-*`,
`/tidy-*`) compose into any of the orchestrators above or run standalone.

## Namespaces

Skills are grouped by namespace for discoverability. Each namespace gathers
skills with a related purpose.

| Namespace      | Purpose                                     | Skills                                                                                                                                                 |
|----------------|---------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| `/lead-*`      | Autonomous orchestrators                    | `/lead-project`, `/lead-bug-hunt`, `/lead-refactor`, `/lead-review`                                                                                    |
| `/implement-*` | Implement tickets (mutate the working tree) | `/implement`, `/implement-batch`, `/implement-project`                                                                                                 |
| `/scope-*`     | Plan and produce tickets                    | `/scope`, `/scope-project`                                                                                                                             |
| `/review-*`    | Advisory audits — no code changes           | `/review-arch`, `/review-test`, `/review-perf`, `/review-a11y`, `/review-health`, `/review-security`, `/review-release`                                |
| `/think-*`     | Reasoning support — no artifacts            | `/think-reframe`, `/think-brainstorm`, `/think-diagnose`, `/think-ach`, `/think-deliberate`, `/think-premortem`, `/think-scrutinize`, `/think-reflect` |
| `/tidy-*`      | Mechanical hygiene                          | `/tidy-docs`, `/tidy-git`                                                                                                                              |
| `/bug-*`       | Find and fix bugs                           | `/bug-fix`, `/bug-hunt`                                                                                                                                |
| `/test-*`      | Test-quality work                           | `/test-mutation`                                                                                                                                       |
| (standalone)   | Skills that don't share a namespace         | `/refactor`, `/pre-compact`, `/release`                                                                                                                |

The `/lead-*` and `/implement-*` namespaces additionally share an autonomy
discipline (commander's intent, pre-loaded options, pre-rebutted
recommendations, risk budgets) — see
[references/autonomy.md](references/autonomy.md). The `/think-*` namespace
shares a design discipline (practitioner-sourced countermeasures to specific
cognitive failure modes) — see [references/think.md](references/think.md).

## Choosing a Workflow

Not everything needs the full pipeline. Enter at the level that matches your
task:

| You want to...                                                                              | Use                  |
|---------------------------------------------------------------------------------------------|----------------------|
| Drive a project to completion autonomously, deciding what to work on                        | `/lead-project`      |
| Implement an entire multi-batch project autonomously                                        | `/implement-project` |
| Implement a batch of related tickets                                                        | `/implement-batch`   |
| Implement a single ticket or feature                                                        | `/implement`         |
| Plan a multi-batch project with adversarial review                                          | `/scope-project`     |
| Plan a single feature and create a ticket                                                   | `/scope`             |
| Fix a bug with diagnosis and root-cause analysis                                            | `/bug-fix`           |
| Proactively hunt for bugs before they're reported                                           | `/bug-hunt`          |
| Iterate hunt → fix until bugs converge below a severity floor (autonomous)                  | `/lead-bug-hunt`     |
| Comprehensively refactor (tactical + architectural + tactical, autonomous)                  | `/lead-refactor`     |
| Pressure-test a problem's framing before solving it                                         | `/think-reframe`     |
| Brainstorm approaches to a goal                                                             | `/think-brainstorm`  |
| Reason about why a phenomenon is happening                                                  | `/think-diagnose`    |
| Narrow among competing hypotheses against evidence                                          | `/think-ach`         |
| Make a hard decision with adversarial deliberation                                          | `/think-deliberate`  |
| Imagine how a plan could fail, or how a hypothetical catastrophe could hit a running system | `/think-premortem`   |
| Scrutinize an idea or plan before committing to it                                          | `/think-scrutinize`  |
| Reflect on a completed experience to update beliefs                                         | `/think-reflect`     |
| Clean up code quality (DRY, dead code, naming)                                              | `/refactor`          |
| Rethink module boundaries and architecture                                                  | `/review-arch`       |
| Survey the test suite and surface gaps as tickets                                           | `/review-test`       |
| Verify test quality via mutation testing                                                    | `/test-mutation`     |
| Tidy all project documentation                                                              | `/tidy-docs`         |
| Pre-release readiness check                                                                 | `/review-release`    |
| Cut a versioned release (preflight + plan + execute)                                        | `/release`           |
| Audit web content for accessibility barriers                                                | `/review-a11y`       |
| First-pass strategic orientation on a repo    
````
