systematic-debugging

Diagnose software bugs through a four-phase root cause investigation workflow.

1|Updated Jun 17, 2026
One-click install
npx skills add https://github.com/specdog/collar --skill systematic-debugging-specdog
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/specdog/collar/tree/main/skills/systematic-debugging
Command: npx skills add https://github.com/specdog/collar --skill systematic-debugging-specdog

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Random fixes and guess-and-check patching waste hours and introduce new bugs. This Skill enforces a disciplined four-phase debugging process that finds the root cause before any fix is attempted, preventing symptom-only patches and repeated failed fix attempts. ## Core Features & Use Cases - Four-Phase Process: Root cause investigation, pattern analysis, hypothesis testing, and implementation, each with explicit completion criteria. - Evidence Gathering: Read error messages fully, reproduce issues consistently, check recent git changes, and trace data flow across component boundaries. - Rule of Three: After three failed fixes, stop and question the architecture instead of attempting a fourth patch. - Use Case: A failing pytest suite in production gets traced from the error message through recent commits and data flow to the exact source of the bad value, then fixed with a regression test proving the fix. ## Quick Start Use the systematic-debugging skill to investigate why this test is failing and find the root cause before proposing 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 debug a failing test systematically?▼

Start by reading the full error message and stack trace, then reproduce the failure consistently with pytest. Check recent git changes, trace the data flow to find where the bad value originates, and only then form a hypothesis and test it with the smallest possible change.

What is root cause analysis in debugging?▼

Root cause analysis means identifying why a bug happens before fixing it, rather than patching symptoms. It involves reproducing the issue, gathering evidence at component boundaries, and tracing bad values upstream to their source.

When should I stop trying fixes and rethink the architecture?▼

Stop after three failed fix attempts. If each fix reveals new problems in different places or requires massive refactoring, the pattern indicates an architectural problem that needs discussion rather than a fourth patch.

How do I debug issues across multiple components like API and database?▼

Add diagnostic logging at each component boundary to capture what data enters and exits each layer. Run the system once to gather evidence showing where it breaks, then investigate that specific component instead of guessing.

Why do quick fixes without investigation cause more bugs?▼

Quick fixes address symptoms rather than root causes, so the underlying issue persists and resurfaces elsewhere. Bundling multiple changes also makes it impossible to isolate what worked, and untested fixes frequently introduce regressions.