systematic-debugging

Diagnose software bugs through a four-phase root cause investigation methodology.

1|Updated Jun 21, 2026
One-click install
npx skills add https://github.com/tapway/shogun-os --skill systematic-debugging-tapway
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/tapway/shogun-os/tree/main/skills/general/systematic-debugging
Command: npx skills add https://github.com/tapway/shogun-os --skill systematic-debugging-tapway

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires debugpy, remote-pdb, chrome-remote-interface, and includes references (resource) components.

What problem does it solve? Random fixes and guess-and-check patching waste hours and introduce new bugs. This Skill enforces a disciplined debugging process that always finds the root cause before attempting any fix, preventing symptom patches that mask underlying issues. ## Core Features & Use Cases - Four-Phase Methodology: Phase 1 investigates root cause (read errors, reproduce, trace data flow), Phase 2 analyzes patterns against working examples, Phase 3 tests a single hypothesis minimally, Phase 4 implements a verified fix with a regression test. - The Iron Law: No fixes without root cause investigation first, with red-flag detection that stops rationalizations like "quick fix for now" and escalates to architectural review after three failed fix attempts. - Language-Specific Debugger Guides: Reference docs cover Node.js debugging via node inspect and Chrome DevTools Protocol, plus Python debugging via pdb, debugpy, and remote-pdb for long-lived processes. - Use Case: A failing API integration returns intermittent HTTP 429 errors. Instead of guessing, you reproduce the failure, trace the batch loop, identify the missing rate-limit throttle, add a minimal delay, and verify with a regression test. ## Quick Start Use the systematic-debugging skill to investigate why my test suite fails and find the root cause 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 failing test systematically instead of guessing?

Follow the four-phase process: read the full error and stack trace, reproduce the failure consistently, check recent changes with git log and diff, then trace the data flow to the root cause. Only after understanding why it fails should you form one hypothesis and test it with a minimal change.

How do I debug Node.js with breakpoints from the terminal?

Use the built-in node inspect REPL or start the process with node --inspect-brk to pause on the first line. Set breakpoints with sb('file.js', line), step with n/s/o, and drop into a repl to inspect local and closure variables.

How do I attach a debugger to a running Python process?

Use debugpy with python -m debugpy --listen 127.0.0.1:5678 --pid <pid> to inject into a running process, or add remote-pdb's set_trace() in code and connect via nc 127.0.0.1 4444 for a plain pdb prompt.

Why does pdb not work when running pytest with xdist?

pdb cannot function under pytest-xdist because tests run in parallel worker processes without an interactive terminal. Run the single test with -p no:xdist or -n 0 to get a working pdb prompt.

When should I stop trying fixes and question the architecture?

Stop after three failed fix attempts. If each fix reveals new coupling or creates symptoms elsewhere, the pattern indicates an architectural problem rather than a simple bug, and you should discuss refactoring with the user before attempting more fixes.

When should I not use a systematic debugging process?

Skip it for feature development, known issues with documented fixes, and simple configuration typos. The methodology targets unknown root causes in bugs, test failures, performance problems, and integration issues.