⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v10.1.0

bug-fix

chrisallenlane@chrisallenlane⭐ 20 stars· last commit 6mo ago· 0 open issues

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.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 20 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// 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-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.

NamespacePurposeSkills
/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 implements 
  • README.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

// REPO STATS

20 stars
0 open issues
Last commit: 6mo ago