systematic-debugging

Reproduce software failures, rank hypotheses, and apply targeted fixes with regression tests.

31|8|Updated Apr 10, 2026

Search Tags:#debugging #root cause analysis #defense-in-depth #post-mortem #hypothesis testing #instrumentation #regression testing

Ready to run

npx skills add https://github.com/itallstartedwithaidea/agent-skills --skill systematic-debugging-itallstartedwithaidea

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/itallstartedwithaidea/agent-skills/tree/main/skills/software-dev/systematic-debugging
Command: npx skills add https://github.com/itallstartedwithaidea/agent-skills --skill systematic-debugging-itallstartedwithaidea

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill prevents unreliable, trial-and-error bug fixing by guiding an agent through disciplined root-cause analysis before any code changes.

Core Features & Use Cases

Reproduce first, never guess: Creates a minimal, reliable reproduction case and verifies the failure is observable before proceeding.
Rank hypotheses with evidence: Generates multiple plausible causes, ranks them by likelihood, and maintains a clear causal chain from observation to conclusion.
Test one variable at a time: Eliminates hypotheses via minimal instrumentation to confirm or refute each candidate root cause.
Fix with defense-in-depth: Applies a targeted corrective change plus preventive hardening (validation, assertions, monitoring) and writes a regression test to stop recurrence.
Close the loop with a post-mortem: Documents root cause, fix rationale, and preventive measures for future learning and consistency.

Quick Start

Use the systematic-debugging skill to analyze a failing test by reproducing the bug, generating ranked hypotheses, testing the top candidate, applying a targeted fix, and adding defense-in-depth plus a regression test.

Frequently Asked Questions about systematic-debugging

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

FAQPage Schema

What is systematic debugging and when should I use it for root cause analysis?▼

Systematic debugging isolates the root cause of unexpected software failures to enable correct, repeatable fixes. Use it for failing tests, unclear stack traces, environment-specific behavior, or cases where prior fixes failed and multiple plausible causes exist.

How do I fix inconsistent software failures without guessing or trial and error?▼

To fix inconsistent software failures without guessing, reproduce the bug first, formulate and rank multiple hypotheses by likelihood, test one variable at a time using minimal instrumentation, then apply a targeted fix with regression testing and defense-in-depth hardening.

What's the best way to find a root cause when stack traces are unclear?▼

The best way to find a root cause with unclear stack traces is to generate multiple plausible hypotheses, rank them by likelihood, and eliminate candidates via minimal instrumentation to confirm a single root cause before applying a corrective code change.

Can I use hypothesis testing to debug environment-specific behavior?▼

Yes, you can use hypothesis testing to debug environment-specific behavior by creating a minimal, reliable reproduction case, verifying the failure is observable, and testing one variable at a time to isolate the exact environmental cause.

How do I prevent regression after applying a targeted bug fix?▼

Prevent regression after a targeted bug fix by applying defense-in-depth hardening like validation, assertions, and monitoring, and by writing a specific regression test to stop recurrence. Close the loop by documenting the root cause and fix rationale in a post-mortem.

Why do my trial-and-error code fixes keep failing to resolve the bug?▼

Trial-and-error code fixes keep failing because they lack disciplined root-cause analysis. Without reproducing the bug first and ranking hypotheses with evidence, you risk treating symptoms rather than isolating the single root cause and applying a targeted corrective change.