systematic-debugging

Debug technical issues through four-phase root-cause investigation and failing-test-first fixes.

Updated Apr 29, 2026
One-click install
npx skills add https://github.com/pgm1980/stryker-netx --skill systematic-debugging-pgm1980
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/pgm1980/stryker-netx/tree/main/.claude/skills/systematic-debugging
Command: npx skills add https://github.com/pgm1980/stryker-netx --skill systematic-debugging-pgm1980

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

It prevents wasted effort and new bugs by forcing you to identify the true root cause of failures before proposing any changes.

Core Features & Use Cases

  • Iron Law root-cause mandate: do not propose fixes until Phase 1 (root-cause investigation) is complete.
  • Four-phase debugging workflow: investigation → pattern analysis → single-hypothesis testing → implementation with a failing test.
  • Pressure-resistant decision rules: explicit STOP conditions when you catch yourself rationalizing quick patches, especially under time pressure.
  • Failure recovery guidance: if a hypothesis test fails, create a new hypothesis rather than stacking more changes; if 3+ fixes fail, question architecture.

Quick Start

Use the skill when you hit any bug, test failure, or unexpected behavior by following Phase 1 until you can state the root cause, then proceed to hypothesis testing and a single root-cause fix.

Frequently Asked Questions about systematic-debugging

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

FAQPage Schema
How do I find the root cause of a bug before applying a fix?

To find the root cause of a bug, gather evidence and reproduce the issue first, then analyze patterns and test a single hypothesis before implementing a failing-test-first fix. This systematic debugging approach eliminates guesswork and prevents patching symptoms.

What is the best way to debug race conditions and test failures?

The best way to debug race conditions and test failures is using hypothesis testing: reproduce the event, analyze patterns, isolate a single variable, and verify with a minimal test. If the hypothesis fails, create a new one rather than stacking patches.

Why does my debugging process result in recurring build failures?

Debugging build failures often recurs when fixes target symptoms instead of root causes. Without completing evidence gathering and pattern analysis first, developers risk stacking multiple unsuccessful fixes, which introduces new bugs and complicates the architecture.

How do I stop myself from applying quick patches under time pressure?

To stop applying quick patches under time pressure, enforce explicit STOP conditions when rationalizing changes. If three or more fixes fail, halt hypothesis testing entirely, question the architecture, and reanalyze the original root cause evidence.

When should I question architecture during root cause analysis?

You should question architecture during root cause analysis when three or more sequential fix attempts fail. Instead of stacking more changes, stop debugging, reanalyze the initial evidence, and investigate whether the integration problem stems from structural flaws.

Does systematic debugging work for multi-component integration problems?

Yes, systematic debugging works for multi-component integration problems by applying a four-phase workflow: evidence gathering, pattern analysis, single-hypothesis testing, and failing-test-first implementation to isolate unexpected runtime behavior across single and complex systems.