systematic-debugging

Diagnose bugs and test failures through a four-phase root-cause investigation process.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Random fixes and guess-and-check patches waste time, mask underlying issues, and introduce new bugs. This Skill enforces a disciplined root-cause-first workflow so every fix addresses the actual cause instead of the symptom. ## Core Features & Use Cases - Four-Phase Process: Root cause investigation, pattern analysis, hypothesis testing, and implementation, each gated before the next begins. - Multi-Component Evidence Gathering: Trace data flow across component boundaries (CI, build, services, databases) using logs and non-mutating diagnostics. - Escalation Rules: After three failed fixes, stop and question the architecture rather than attempting a fourth patch. - Use Case: A CI build fails after a dependency update. Instead of tweaking configs blindly, reproduce the failure, check recent changes, form a single hypothesis, and verify one minimal fix at a time. ## Quick Start Use the systematic-debugging skill to investigate why the login integration test started failing after the last commit 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 test failure systematically?▼

Start by reading the full error message and stack trace, then reproduce the failure consistently and check recent changes via git diff. Form one specific hypothesis, test it with the smallest possible change, and only implement a fix after confirming the root cause.

What is root cause analysis in software debugging?▼

Root cause analysis identifies the underlying source of a bug rather than patching its symptoms. It involves reproducing the issue, tracing data flow backward through the call stack, and comparing broken behavior against working examples before writing any fix.

How to debug failures in multi-component systems?▼

Gather boundary evidence at each layer by inspecting what data enters and exits every component using existing logs, traces, and non-mutating diagnostics. This reveals which layer fails, such as secrets reaching the workflow but not the build script, so you investigate only that component.

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

Stop after three failed fix attempts, especially when each fix reveals a new problem in a different place or requires massive refactoring. This pattern indicates an architectural problem, so discuss fundamentals with your team before attempting more patches.

Can read-only investigators use a systematic debugging process?▼

Yes, read-only investigators can inspect code, reproduce issues with non-mutating commands, and report hypotheses. They must not add tests, instrumentation, files, or fixes, and project instructions override the skill's default guidance.