systematic-debugging

Diagnose software bugs through four-phase root cause investigation before applying fixes.

Updated Jul 28, 2026
One-click install
npx skills add https://github.com/christian-byrne/comfy-skills --skill systematic-debugging-christian-byrne
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/christian-byrne/comfy-skills/tree/main/skills/systematic-debugging
Command: npx skills add https://github.com/christian-byrne/comfy-skills --skill systematic-debugging-christian-byrne

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Developers often apply quick patches based on pattern-matching instead of finding the actual root cause, which leads to regressions and recurring bugs. This Skill enforces a disciplined investigation process that halts feature work, preserves evidence, and requires root cause confirmation before any fix is written. ## Core Features & Use Cases - Four-Phase Debugging Workflow: Root Cause Tracing, Pattern Analysis, Hypothesis Testing, and test-first Implementation with regression verification. - Fresh Eyes Escape Hatch: After two disproven hypotheses, dispatch a fresh subagent with only the symptom and entry point to break out of anchoring bias. - Defense-in-Depth Guidance: Reference material on adding validation at multiple layers and replacing flaky timeouts with condition-based polling. - Use Case: A test suite fails intermittently in CI. Instead of retrying or patching the assertion, follow the phases to reproduce the failure, trace the call stack back to a race condition, write a failing test that proves the root cause, then apply a minimal fix. ## Quick Start Ask the agent to debug a failing test or error using the systematic debugging process, starting with root cause investigation before any 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 instead of guessing?▼

Trace backward from the symptom through the call stack to find where bad data or state originates. Form a hypothesis, design a test to prove or disprove it, and iterate until you have high confidence before writing any fix.

How to debug intermittent test failures in CI?▼

First reproduce the failure reliably, then analyze when it happens and what changed recently. Replace arbitrary timeouts with condition-based polling, since fixed delays cause flakiness on machines with different speeds.

What should I do when my debugging hypotheses keep failing?▼

After two or more disproven hypotheses, you are likely anchored by your investigation context. Dispatch a fresh subagent with only the symptom and entry point file, with no prior theories, and compare its conclusions against yours.

Why should I write a failing test before fixing a bug?▼

A failing test proves you found the actual root cause and serves as the acceptance criterion for the fix. When the test passes after your minimal fix, you have verified the fix works rather than assumed it.

When is it okay to skip root cause investigation for simple bugs?▼

The skill argues investigation is never optional: if a bug is truly simple, investigation takes 30 seconds and confirms the hunch. Skipping it means pattern-matching, which the skill notes is wrong roughly 40 percent of the time.