skills.rest
jwilger
jwilgerCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

debugging-protocol

Guide engineers through a four-phase debugging protocol for root-cause identification.

Updated Jul 1, 2026
Search Tags:#testing#debugging#investigation#software-quality#root-cause-analysis#hypothesis-testing#debug-protocol
One-click install
npx skills add https://github.com/jwilger/claude-code-plugins --skill debugging-protocol-jwilger
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: debugging-protocol
Source: https://github.com/jwilger/claude-code-plugins/tree/main/sdlc/skills/debugging-protocol
Command: npx skills add https://github.com/jwilger/claude-code-plugins --skill debugging-protocol-jwilger

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill defines a disciplined, four-phase debugging protocol to identify root causes before applying fixes, preventing symptom fixes and reducing technical debt.

Core Features & Use Cases

  • Four-Phase Investigation: Root Cause Investigation, Pattern Analysis, Hypothesis Testing, and Implementation.
  • One Hypothesis at a Time: Test a single theory with minimal changes to ensure traceable results.
  • Escalation After Three Failures: Stop fixes and re-evaluate architecture when three attempts fail.
  • Language- and framework-agnostic: Applicable to bugs, test failures, and unexpected behavior across environments.

Quick Start

Follow Phase 1 through Phase 4 in sequence for each defect:

  1. Conduct Root Cause Investigation by reading the full error, reproducing the bug, and collecting context (git diff, git log).
  2. Perform Pattern Analysis by locating working examples and noting differences.
  3. Write and test a single Hypothesis; implement the minimal change to test it.
  4. If the hypothesis fails, revert the change and form a new hypothesis; repeat. After three failed attempts, escalate to architectural review.

Frequently Asked Questions about debugging-protocol

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I find the root cause of a software bug instead of just fixing the symptom?▼

Hypothesis testing requires testing a single theory with minimal changes to ensure traceable results. You write and test one hypothesis at a time, implementing the smallest change possible to verify or refute your theory before moving forward.

What is the best way to debug test failures across different programming languages?▼

A language-agnostic debugging protocol applies to bugs, test failures, and unexpected behavior across environments. It guides you through pattern analysis by locating working examples and noting differences to identify the root cause regardless of the framework.

How do I systematically debug a software defect step by step?▼

Follow a four-phase debugging process: conduct root cause investigation, perform pattern analysis, test a single hypothesis with minimal changes, and implement the fix. Document each phase and create failing tests to verify the defect is resolved.

When should I stop trying to fix a bug and re-evaluate the architecture?▼

After three failed hypothesis attempts, you should stop applying fixes and escalate to an architectural review. This prevents compounding technical debt and forces a re-evaluation of the underlying design when isolated fixes are not working.

How does pattern analysis work when investigating unexpected software behavior?▼

Pattern analysis works by locating working examples of similar functionality and noting the differences from the failing case. This comparative approach helps isolate variables and identify what specific change or condition triggers the unexpected behavior.

Related Skills

Explore More Software Engineering Skills→
sQVesQVe

debug-issue

Diagnose bugs by tracing evidence and generating a BR issue template.

Community
Advanced
pedropaulovcpedropaulovc
3

systematic-debugging

Enforce a four-phase root-cause debugging process from investigation to verified implementation.

Community
Advanced
outfitter-devoutfitter-dev
6

debugging

Debug software issues through evidence collection, variable isolation, hypothesis formulation, and testing.

Official
Advanced
Im5tuIm5tu
6

systematic-debugging

Identify root causes of software bugs through a four-phase debugging process.

Community
Advanced