systematic-debugging

Diagnose bugs through a four-phase root cause investigation process before proposing fixes.

2|Updated Mar 7, 2025

Search Tags:#software engineering #debugging #troubleshooting #root cause analysis #test failures #hypothesis testing #error diagnosis

Ready to run

npx skills add https://github.com/AbdelrhmanUZaki/KnowledgeNuggets --skill systematic-debugging-abdelrhmanuzaki

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/AbdelrhmanUZaki/KnowledgeNuggets/tree/main/2-setup/shared/gemini/config/skills/systematic-debugging
Command: npx skills add https://github.com/AbdelrhmanUZaki/KnowledgeNuggets --skill systematic-debugging-abdelrhmanuzaki

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Random fixes and guess-and-check patching waste time, mask underlying issues, and introduce new bugs. This Skill enforces a disciplined debugging methodology that finds the root cause before any fix is attempted. ## Core Features & Use Cases - Four-Phase Process: Root cause investigation, pattern analysis, hypothesis testing, and verified implementation, each gated before proceeding. - Multi-Component Evidence Gathering: Instrument component boundaries (CI, build, signing, APIs, databases) with diagnostic logging to locate where failures originate. - Architectural Escalation: After three failed fix attempts, stop and question the architecture instead of attempting a fourth patch. - Use Case: When a test fails in a CI pipeline, trace data flow across workflow, build script, and signing layers with targeted logging, form a single hypothesis, and verify one minimal fix with a failing test. ## Quick Start Use the systematic-debugging skill to investigate this failing test and find its root cause before suggesting 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 verify with a failing test case before implementing the fix.

How to find root cause in multi-component systems?▼

Add diagnostic logging at each component boundary to capture what data enters and exits every layer, such as workflow, build script, and signing steps. Run once to gather evidence showing which layer breaks, then 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 fixes.

Why do quick fixes cause more bugs?▼

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

Can I skip the debugging process for simple bugs?▼

No, simple bugs have root causes too, and the process is fast for straightforward issues. Skipping investigation under time pressure leads to guess-and-check thrashing that takes longer than systematic diagnosis.