systematic-debugging

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

Updated Sep 3, 2024
One-click install
npx skills add https://github.com/eminboydak/duckTerm --skill systematic-debugging-eminboydak
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/eminboydak/duckTerm/tree/main/.agents/skills/systematic-debugging
Command: npx skills add https://github.com/eminboydak/duckTerm --skill systematic-debugging-eminboydak

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Developers under time pressure often apply quick symptom fixes that fail repeatedly, wasting hours on guess-and-check debugging. This Skill enforces a disciplined investigation process that finds the actual root cause before any fix is attempted. ## Core Features & Use Cases - Four-Phase Debugging Framework: Structured workflow covering root cause investigation, pattern analysis, hypothesis testing, and verified implementation. - Supporting Techniques: Includes root cause tracing through call stacks, defense-in-depth validation at multiple layers, and condition-based waiting to replace flaky arbitrary timeouts in tests. - Pollution Bisection Script: A bash script that runs test files one-by-one to identify which test creates unwanted files or state. - Use Case: When a test fails intermittently or a production bug resists obvious fixes, load this Skill to systematically trace the failure to its source instead of stacking retries and sleep calls. ## Quick Start Use the systematic-debugging skill to investigate why this test failure keeps happening instead of guessing at fixes.

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 fixing symptoms?

Follow a four-phase process: investigate the root cause by reading errors and reproducing consistently, analyze patterns against working examples, form and test a single hypothesis, then implement one verified fix. Never propose fixes before completing the investigation phase.

How to fix flaky tests caused by arbitrary timeouts?

Replace setTimeout and sleep calls with condition-based waiting that polls for the actual condition you care about, such as an event appearing or state changing. Poll every 10ms with a timeout, which eliminated flakiness and ran 40% faster in real debugging sessions.

How do I find which test is polluting my repository state?

Use the find-polluter.sh bisection script with the polluted path and a test file pattern. It runs each test file individually and stops at the first one that creates the unwanted file or directory, identifying the exact polluting test.

What should I do when multiple fix attempts keep failing?

Stop after three failed fixes and question the architecture rather than attempting a fourth fix. Repeated failures where each fix reveals new problems elsewhere indicate a fundamental design problem that requires architectural discussion, not more patches.

When should I add validation at multiple layers of my code?

Add defense-in-depth validation after fixing a bug caused by invalid data. Validate at the entry point, business logic, environment guards, and debug instrumentation layers so the bug becomes structurally impossible rather than merely patched at one location.