Why does the protocol suggest stopping after three failed fix attempts?

Repeated failures usually signal that the problem is architectural or a domain modeling issue rather than a simple bug, necessitating an escalation to a design review.

What is the 'Iron Law' in this protocol?

The Iron Law states that no fix should be attempted until a thorough root cause investigation is completed to prevent masking deeper issues with symptom-level patches.

How does this integrate with Test-Driven Development (TDD)?

It complements TDD by requiring a failing test for reproduction before any fix is implemented, ensuring the final solution is verified, targeted, and permanent.

How does the 4-phase process work?

It guides you through Root Cause Investigation, Pattern Analysis (comparing with working code), Hypothesis Testing (one change at a time), and finally Implementation.

Can this skill be used with any programming language?

Yes, the Debugging Protocol is universal and framework-agnostic, focusing on logical investigation principles rather than language-specific debugging tools.

Debugging Protocol

Name: Debugging Protocol
Author: jwilger

byjwilger

•

Developer Tools

Implements a systematic 4-phase methodology to identify and resolve root causes of software bugs rather than just patching symptoms.

The Debugging Protocol skill transforms how Claude approaches bug fixing by enforcing a disciplined, four-phase investigation process: Root Cause Investigation, Pattern Analysis, Hypothesis Testing, and Implementation. It prevents 'symptom-fixing' through the 'Iron Law,' ensuring developers understand why a bug occurs before changing any code. This skill is ideal for complex systems where random debugging wastes time, providing a clear path from reproduction to a verified, permanent fix while preventing technical debt and architectural regression.

Key Features

01Enforcement of the 'Iron Law': No code changes without prior investigation

027 GitHub stars

03Single-hypothesis testing strategy to isolate variables and avoid confusion

04Automatic escalation triggers to architecture review after three failed fix attempts

05Pattern analysis to compare failing code with successful execution examples

06Four-phase systematic investigation workflow (Root Cause to Implementation)

Use Cases

01Investigating intermittent test failures and race conditions in CI/CD pipelines

02Eliminating technical debt caused by repeated symptom-level patches in legacy code

03Tracing root causes in complex multi-component or distributed microservices

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add jwilger/claude-code-plugins debugging-protocol

For use in Claude.ai and ChatGPT

Download Skill