systematic-debugging

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

Updated Jun 11, 2026
One-click install
npx skills add https://github.com/marcocpt/trae_skills --skill systematic-debugging-marcocpt
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/marcocpt/trae_skills/tree/main/systematic-debugging
Command: npx skills add https://github.com/marcocpt/trae_skills --skill systematic-debugging-marcocpt

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve? Random guess-and-check fixes waste hours, mask underlying defects, and introduce new bugs. This Skill enforces a disciplined debugging methodology that finds the actual root cause before any fix is attempted, even under time pressure or social pressure to apply quick patches. ## Core Features & Use Cases - Four-Phase Process: Root cause investigation, pattern analysis, hypothesis testing, and implementation, with explicit gates preventing you from proposing fixes before completing Phase 1. - Pressure-Resistant Rules: Anti-patterns, rationalization tables, and red-flag phrases that stop shortcut behavior like "just add a retry" or "fix multiple things at once". - Supporting Techniques: Root-cause tracing up the call stack, defense-in-depth validation at multiple layers, condition-based waiting to replace flaky timeouts, and a bisection script to find test polluters. - Use Case: A test fails intermittently in CI. Instead of adding sleep calls, you trace the data flow backward, find the empty variable causing the failure, fix it at the source, and add layered validation so it cannot recur. ## 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 failing test systematically instead of guessing?

Follow the four phases: read the full error and reproduce the failure consistently, compare against working examples in the same codebase, form one specific hypothesis and test it minimally, then implement a single fix verified by a failing test written first.

How to find the root cause of a bug deep in the call stack?

Trace backward from the error location by asking who called each function and what values were passed, continuing until you find the original trigger point. Add stack-trace logging with console.error before the failing operation if manual tracing stalls.

How do I fix flaky tests caused by timing issues?

Replace hardcoded setTimeout or sleep calls with condition-based waiting that polls for the actual state you need, such as an event appearing or a count being reached. This removes race conditions and typically speeds up test execution.

Should I skip root cause investigation during a production emergency?

No. The skill explicitly states that systematic debugging is faster than repeated guess-and-check cycles, and emergencies are exactly when shortcut fixes cause the most damage. Time pressure is listed as a reason to follow the process, not skip it.

What should I do when three or more fix attempts have failed?

Stop attempting fixes and question the architecture. Repeated failures where each fix exposes new problems elsewhere indicate a structural issue, so discuss whether the underlying pattern is wrong before trying a fourth fix.

How do I find which test is polluting shared state or the filesystem?

Use the included find-polluter.sh bisection script, which runs each test file individually and checks whether the unwanted file or directory appears, stopping at the first test that creates the pollution.