⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
bug-fix
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.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
// README
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
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-batchuntil 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. The /think-* namespace
shares a design discipline (practitioner-sourced countermeasures to specific
cognitive failure modes) — see 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 |
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
skills/bug-fix/SKILL.md7.8 KBupstream ↗
--- 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 implementsREADME.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/chrisallenlane-claude-swe-workflows-skills-bug-fix.md