systematic-debugging

Diagnose observed failures through evidence-based root-cause analysis before changing code.

Updated Mar 26, 2026
One-click install
npx skills add https://github.com/sciman-top/skills-manager --skill systematic-debugging-sciman-top
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/sciman-top/skills-manager/tree/main/overrides/patches/systematic-debugging
Command: npx skills add https://github.com/sciman-top/skills-manager --skill systematic-debugging-sciman-top

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When a bug, failing test, or build break appears, it is tempting to guess at fixes or rewrite large sections of code. This Skill enforces a disciplined workflow that finds the smallest causal explanation for an observed failure before any code is changed, preventing speculative fixes and unnecessary refactors. ## Core Features & Use Cases - Evidence-First Diagnosis: Records expected versus observed behavior and identifies the cheapest command that reproduces the difference. - Falsifiable Hypotheses: Forms one testable cause at a time and uses the cheapest discriminating evidence instead of broad audits or full test suites. - Minimal Causal Fixes: Fixes the causal seam, adds a focused regression test only when it protects the observed failure mode, and stops once verification passes. - Use Case: A CI build breaks after a merge. Instead of reverting blindly, use this Skill to reproduce the failure locally, isolate the exact input causing it, patch that seam, and re-run only the affected test. ## Quick Start Use systematic-debugging to find the root cause of this failing test and fix only the code responsible for it.

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 without guessing at fixes?▼

Record the expected and observed behavior, then find the cheapest command that reproduces the difference. Form one falsifiable hypothesis at a time and use discriminating evidence to confirm or reject it before changing any code.

What is root-cause analysis for software bugs?▼

Root-cause analysis identifies the smallest causal explanation for an observed failure by reading the failing code path and its inputs. The fix targets that causal seam directly rather than symptoms, followed by re-running the reproducer to confirm.

When should I not use a systematic debugging workflow?▼

Do not use it for straightforward implementation tasks with no observed failure. It is designed specifically for diagnosing existing bugs, failing tests, build breaks, or unexpected behavior that needs explanation.

What should I do after two failed debugging attempts?▼

Pause and clarify the disputed semantics or acceptance criterion instead of repeating speculative fixes. Continuing to guess after two failures usually means the problem definition itself is unclear.

Should I add regression tests when fixing a bug?▼

Add a focused regression test only when it protects the specific observed failure mode and is not already covered. Escalate to wider test suites only when the change crosses shared, security, data, migration, or public-contract boundaries.