systematic-debugging
4-phase root cause debugging: understand bugs before fixing.
npx skills add HezaoHezao/poirot --skill systematic-debugging --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# Systematic Debugging ## Overview Random fixes waste time and create new bugs. Quick patches mask underlying issues. **Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure. ## The Iron Law ``` NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST ``` If you haven't completed Phase 1, you cannot propose fixes. ## The Feedback Loop Rule The feedback loop is the debugging work. Before reading code to build a theory, create or identify a **tight** command that can go red on the user's exact symptom and green when the bug is fixed. A tight loop is fast, deterministic, agent-runnable, and specific enough to catch this bug — not merely "doesn't crash". When a clean repro is hard, spend disproportionate effort building the loop. ## When to Use Use for ANY technical issue: test failures, bugs in production, unexpected behavior, performance problems, build failures, integration issues. **Use ESPECIALLY when:** - Under time pressure (emergencies make guessing tempting) - "Just one quick fix" seems obvious - You've already tried multiple fixes - Previous fix didn't work - You don't fully understand the issue ## The Four Phases You MUST complete each phase befo
- Overview
- The Iron Law
- The Feedback Loop Rule
- When to Use
- The Four Phases
- Phase 1: Root Cause Investigation
- 1. Read Error Messages Carefully
- 2. Build a Tight Feedback Loop
- 3. Check Recent Changes
- 4. Gather Evidence in Multi-Component Systems
- 5. Trace Data Flow
- Phase 1 Completion Checklist
- Phase 2: Pattern Analysis
- 0. Minimize the Reproduction
Run a specific failing test
pytest tests/test_module.py::test_name -v
Or run a scripted repro
python scripts/repro_bug.py
Or run a high-repetition flaky repro
for i in {1..100}; do pytest tests/test_flake.py::test_name -q || break; done
git log --oneline -10
git diff
git log -p --follow src/problematic_file.py | head -100
Find where the function is calledWhat does the systematic-debugging skill do?
4-phase root cause debugging: understand bugs before fixing.
How do I install it?
Run `npx skills add HezaoHezao/poirot --skill systematic-debugging --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From HezaoHezao/poirot, a repository with 193 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.