skills.rest
kangjuhyup
kangjuhyupCOMMUNITY
Explore all skills by this author →
GitHub

systematic-debugging

Guides root cause investigation through a four-phase debugging process before proposing fixes.

Updated Sep 6, 2026
Search Tags:#typescript#test automation#debugging#troubleshooting#root cause analysis#bash#flaky tests
One-click install
npx skills add https://github.com/kangjuhyup/study --skill systematic-debugging-kangjuhyup
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/kangjuhyup/study/tree/main/scoped-superpowers-ab/workflow-code-benchmark/fixture/workflows/full/skills/systematic-debugging
Command: npx skills add https://github.com/kangjuhyup/study --skill systematic-debugging-kangjuhyup

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve? When facing bugs, test failures, or unexpected behavior, it is tempting to apply quick symptom fixes that fail repeatedly and waste hours. This Skill enforces a disciplined investigation process so the actual root cause is found and fixed instead of patched over. ## Core Features & Use Cases - Four-Phase Process: Enforces Root Cause Investigation, Pattern Analysis, Hypothesis Testing, and Implementation in strict order, with explicit stop conditions when fixes fail. - 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: Ships a bash script that runs test files one by one to identify which test creates unwanted files or state. - Use Case: A test suite is flaky with 60% pass rate due to guessed setTimeout delays. Apply condition-based waiting helpers to poll for actual events, raising the pass rate to 100% while running faster. ## Quick Start Ask the AI to debug a failing test or production bug using the systematic debugging process, starting with root cause investigation before 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 find the root cause of a bug instead of fixing symptoms?▼

Follow the four-phase process: read error messages fully, reproduce the issue consistently, check recent changes, and trace data flow backward through the call stack until you find the original trigger. Only then form a single hypothesis and test it with the smallest possible change.

How to fix flaky tests caused by setTimeout delays?▼

Replace arbitrary timeouts with condition-based waiting that polls for the actual event or state you need, such as waitForEvent or waitForEventCount. Poll every 10ms with a clear timeout error, which removed flakiness and ran 40% faster in the documented case.

What should I do when my first debugging fix doesn't work?▼

Stop and form a new hypothesis rather than stacking more fixes. If three or more fixes have failed, treat it as an architectural problem and discuss the design with your team before attempting another fix.

How do I find which test is creating unwanted files or state?▼

Use the included find-polluter.sh bash script with the path to check and a test file pattern. It runs each test file individually and stops at the first one that creates the pollution, reporting the offending test.

When is it acceptable to skip systematic debugging for simple bugs?▼

According to the skill, never. Simple bugs have root causes too, and the process is fast for simple issues. Skipping investigation under time pressure leads to repeated failed fixes that cost more time overall.

Related Skills

Explore More Software Engineering Skills→
YaugourtYaugourt
2

investigate

Identify root causes of bugs by analyzing logs and code paths.

Community
Advanced
yonyon
3

fix-bug

Diagnose and fix software bugs using a Test-Driven Development workflow.

Community
Advanced
bacchus-labsbacchus-labs
4

defense-in-depth

Validate data across entry points, business logic, environment guards, and debug instrumentation.

Official
Advanced
davpatel605-beepdavpatel605-beep

node-inspect-debugger

Debug Node.js applications using the inspector and Chrome DevTools Protocol.

Community
Advanced