debug-systematic
A disciplined, evidence-based debugging framework that walks you through reproducing issues reliably, narrowing scope to the failing component, understanding root causes through the scientific method, and implementing minimal fixes with regression tests. Eliminates guesswork and ensures you address the actual problem, not just symptoms.
debug-systematic provides a 4-phase protocol to systematically reproduce, isolate, diagnose, and fix complex bugs.
AI-generated summary based on this skill's SKILL.md
Install
travisjneuman/.claude/debug-systematic · repository language: JavaScript
git clone https://github.com/travisjneuman/.claude
cp -r .claude/skills/debug-systematic ~/.claude/skills/debug-systematicnpx skillfed install travisjneuman/.claude/debug-systematicFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How to debug complex bugs systematically?
debug-systematic provides a 4-phase protocol for investigating complex, intermittent, or mysterious bugs. The framework guides you through reproducing issues reliably, narrowing scope to the failing component using techniques like binary search and git bisect, understanding root causes through the scientific method, and implementing minimal fixes with regression tests. This disciplined, evidence-based approach eliminates guesswork and ensures you address the actual problem, not just symptoms.
What is the 4 phase debugging methodology?
debug-systematic's 4-phase protocol structures bug investigation into: (1) establishing reliable reproduction steps and environment documentation, (2) narrowing down bug location and isolating root cause in large codebases using binary search and git bisect, (3) applying the scientific method to diagnose why bugs occur, not just where they are, and (4) preventing regressions by writing tests and avoiding common debugging anti-patterns. This systematic approach transforms mysterious failures into solvable problems.
How can I find the root cause of intermittent failures?
debug-systematic teaches you to isolate intermittent bugs by first establishing reliable reproduction steps and documenting your environment. Then narrow down the bug location in large codebases using binary search and git bisect to pinpoint when the failure was introduced. Apply the scientific method to diagnose why the bug occurs, not just where it is. Finally, write regression tests to prevent the issue from recurring and avoid common debugging anti-patterns that mask root causes.
How do I narrow down bug location in large codebases?
debug-systematic emphasizes using binary search and git bisect to efficiently isolate failing components in large codebases. These techniques let you quickly identify which commit introduced the regression without manually inspecting thousands of lines. Combined with reliable reproduction steps, you can systematically eliminate half the search space with each iteration. This disciplined approach prevents the common pitfall of random code inspection and ensures you locate the actual source of the problem.
What debugging anti-patterns should I avoid?
debug-systematic helps you prevent regressions by identifying and avoiding common debugging anti-patterns. The framework emphasizes establishing reliable reproduction steps before diving into code, using the scientific method instead of guesswork, and writing tests to catch future regressions. By following the 4-phase protocol and avoiding shortcuts like random code changes or environment-specific fixes, you ensure your solutions address root causes and don't create new bugs.
How does debug-systematic apply the scientific method?
debug-systematic teaches you to diagnose why bugs occur, not just where they are, by applying the scientific method to bug investigation. This means forming hypotheses about root causes, designing tests to validate or refute them, and gathering evidence before implementing fixes. This evidence-based approach transforms debugging from trial-and-error guesswork into disciplined problem-solving, ensuring you understand the actual mechanism behind failures and implement minimal, targeted fixes.
SKILL.md
rendered from the published skill — quoted content, verbatim
Systematic Debugging Protocol
A disciplined, evidence-based approach to debugging that prevents guessing and ensures root cause discovery.
The 4-Phase Protocol
Phase 1: REPRODUCE (Establish Ground Truth)
Goal: Create reliable reproduction steps before ANY investigation.
Actions:
- Document exact steps to trigger the bug
- Record environment specifics (OS, versions, config, memory, network)
- Determine frequency: Always? Sometimes? Specific conditions?
- Capture exact error messages, stack traces, screenshots
- Test on different environments to isolate variables
Key Questions:
- When did it last work correctly?
- What changed since then? (code, deps, config, infrastructure)
- Is it environment-specific?
- Is it data-specific?
- Is it timing-specific?
Output: Clear reproduction steps that reliably trigger the issue.
Phase 2: ISOLATE (Narrow the Scope)
Goal: Reduce the search space from "entire codebase" to
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 1 file
skills/debug-systematic/SKILL.md