How do I install the Systematic Debugging skill?

Run npx skillmds@latest add gustavo-meilus/systematic-debugging in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Systematic Debugging safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Systematic Debugging?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Systematic Debugging free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Systematic Debugging?

gustavo-meilus (@gustavo-meilus) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Systematic Debugging by gustavo-meilus

Name: Systematic Debugging
Author: gustavo-meilus

File contents

Systematic Debugging — Root Cause Protocol

Establishes a rigorous methodology for identifying, isolating, and resolving technical issues before any fix is proposed.

The Debugging Protocol

PHASE 2: PATTERN ANALYSIS

Working examples of similar logic in the codebase are located and examined.
The broken implementation is compared against reference standards or successful instances.
All differences are identified, however minor; no detail is assumed to be irrelevant.

PHASE 3: HYPOTHESIS & MINIMAL TESTING

A single, specific hypothesis is formed: "X is the root cause because Y."
The smallest possible change is made to test the hypothesis. Example: a one-line guard clause rather than a multi-function refactor.
The result is verified before adding more logic. If it fails, the change is reverted and a new hypothesis is formed.

PHASE 4: IMPLEMENTATION & VERIFICATION

A minimal failing test case is created (using the test-driven-development skill).
A single fix addressing the root cause is implemented.
The fix is verified against the test case and checked for regressions.

Red Flags — STOP

"Quick fix for now, investigate later." → STOP. Symptom fixes are failure.
"Just try changing X and see if it works." → STOP. This is guessing, not debugging.
"I'll skip the test; I manually verified it." → STOP. Untested fixes are guaranteed regressions.
"Each fix reveals a new problem in a different place." → STOP. This is a signal of an architectural failure (The 3-Fix Limit).

Rationalization Table

Reference Files

test-driven-development/SKILL.md — Creating failing tests.
verification-before-completion/SKILL.md — Final verification protocol.
sk-pipeline-state/SKILL.md — Debugging state corruption.
root-cause-tracing.md — Backward tracing techniques.

---name: systematic-debuggingdescription: Enforces root-cause investigation before any fix is proposed or implemented. Use when encountering a bug, test failure, or unexpected behavior, before proposing or implementing a fix.---# Systematic Debugging — Root Cause Protocol> Establishes a rigorous methodology for identifying, isolating, and resolving technical issues before any fix is proposed.<overview>Systematic Debugging is based on the Iron Law: **NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST**. It replaces guess-and-check thrashing with a scientific method—Read, Reproduce, Hypothesize, and Test—ensuring that fixes address the underlying problem rather than masking symptoms.</overview><glossary> <term name="Root Cause">The original source of a failure; fixing it prevents the symptom from recurring.</term> <term name="Symptom Fix">A patch that hides a failure without addressing the cause; leads to technical debt and regression.</term> <term name="Iron Law">The non-negotiable rule prohibiting any fix proposal until Phase 1 is complete.</term></glossary>## The Debugging Protocol<protocol>### PHASE 1: ROOT CAUSE INVESTIGATION- **Read**: Complete error messages, stack traces, and logs are read in full — no skimming.- **Reproduce**: A consistent, reliable trigger for the failure is established before proceeding.- **Gather Evidence**: Component boundaries are instrumented to log data ingress/egress. Example: adding `console.log` at each function boundary to observe where a value becomes `undefined`.- **Trace**: Data flow is mapped backward from the failure point to the origin of the bad state.- <HARD-GATE>Phase 1 is complete only when the agent can explain exactly WHAT failed and WHY.</HARD-GATE>### PHASE 2: PATTERN ANALYSIS- Working examples of similar logic in the codebase are located and examined.- The broken implementation is compared against reference standards or successful instances.- All differences are identified, however minor; no detail is assumed to be irrelevant.### PHASE 3: HYPOTHESIS & MINIMAL TESTING- A single, specific hypothesis is formed: "X is the root cause because Y."- The **smallest possible change** is made to test the hypothesis. Example: a one-line guard clause rather than a multi-function refactor.- The result is verified before adding more logic. If it fails, the change is reverted and a new hypothesis is formed.### PHASE 4: IMPLEMENTATION & VERIFICATION- A minimal failing test case is created (using the `test-driven-development` skill).- A single fix addressing the root cause is implemented.- The fix is verified against the test case and checked for regressions.</protocol><invariants>- **No Fix Bundling**: Only the root cause is addressed; "while I'm here" refactors are deferred.- **The 3-Fix Limit**: If three separate fix attempts have failed, **STOP**. This indicates an architectural flaw, not a simple bug. The fundamental pattern is questioned with the human partner before continuing.- **Data Flow Truth**: Fixes are based on observed data state at component boundaries, not on intuition.</invariants>## Red Flags — STOP- "Quick fix for now, investigate later." → **STOP**. Symptom fixes are failure.- "Just try changing X and see if it works." → **STOP**. This is guessing, not debugging.- "I'll skip the test; I manually verified it." → **STOP**. Untested fixes are guaranteed regressions.- "Each fix reveals a new problem in a different place." → **STOP**. This is a signal of an architectural failure (The 3-Fix Limit).## Rationalization Table<rationalization_table>| Excuse | Reality || :--- | :--- || "The issue is too simple for process." | Simple issues have root causes. Process is faster than guessing even for minor bugs. || "Emergency, no time for investigation." | Systematic debugging is 5x faster than guess-and-check thrashing during crises. || "I see the problem, let me fix it." | Seeing a symptom is not the same as understanding the trigger. || "Multiple fixes at once save time." | Bundled fixes make it impossible to isolate the true resolution. |</rationalization_table>## Reference Files- `test-driven-development/SKILL.md` — Creating failing tests.- `verification-before-completion/SKILL.md` — Final verification protocol.- `sk-pipeline-state/SKILL.md` — Debugging state corruption.- `root-cause-tracing.md` — Backward tracing techniques.

Frequently asked questions

Systematic Debugging