systematic-debugging
This skill enforces a disciplined debugging process: establish a tight feedback loop that reproduces the exact symptom, gather evidence across system boundaries, trace data flow to its source, and form testable hypotheses before proposing any fix. By completing each phase sequentially—root cause investigation, pattern analysis, hypothesis testing, and verification—you eliminate guesswork and prevent quick patches from masking deeper issues.
Systematic Debugging guides you through a 4-phase process to identify root causes before fixing bugs.
AI-generated summary based on this skill's SKILL.md
Install
NousResearch/hermes-agent/systematic-debugging · repository language: Python
git clone https://github.com/NousResearch/hermes-agent
cp -r hermes-agent/skills/software-development/systematic-debugging ~/.claude/skills/systematic-debuggingnpx skillfed install NousResearch/hermes-agent/systematic-debuggingFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
What is systematic-debugging and why does it matter?
Systematic-debugging is a disciplined process that enforces root cause investigation before attempting any fix. Rather than patching symptoms, it establishes a tight feedback loop to reproduce the exact failure, gathers evidence across system boundaries, traces data flow to its source, and forms testable hypotheses. This approach eliminates guesswork and prevents quick fixes from masking deeper issues that will resurface later.
How do I establish a reproducible test case for a failing behavior?
Systematic-debugging prioritizes creating a tight feedback loop that reproduces the exact symptom consistently. Start by documenting the precise conditions when the failure occurs, isolate variables one at a time, and build a minimal test case that triggers the problem reliably. This reproducibility is foundational—without it, you cannot confidently verify whether your fix actually addresses the root cause or merely hides the symptom temporarily.
What is the debugging process systematic-debugging recommends?
Systematic-debugging structures debugging into four sequential phases: root cause investigation (gather evidence across system boundaries), pattern analysis (identify what conditions trigger the failure), hypothesis testing (form and validate testable theories about the source), and verification (confirm the fix resolves the actual problem, not just the symptom). Completing each phase in order prevents wasted effort on symptom fixes that mask real issues.
How can I trace data flow in code to find where problems originate?
Systematic-debugging emphasizes systematically narrowing down where a problem originates by tracing data flow to its source. Follow inputs through your system, log state at each boundary, and identify where values diverge from expected behavior. This methodical approach reveals the actual point of failure rather than where symptoms become visible, enabling you to address root causes instead of downstream effects.
How do I debug flaky or intermittent failures with higher confidence?
Systematic-debugging tackles flaky tests by establishing reproducible conditions and gathering comprehensive evidence. Identify environmental factors, timing dependencies, and state interactions that trigger intermittent failures. Use hypothesis testing to isolate which component or interaction is responsible, then verify your fix eliminates the flakiness rather than just reducing its frequency. This scientific approach replaces guessing with confidence.
Why do my fixes keep failing and how do I avoid that?
Systematic-debugging prevents recurring failures by avoiding quick patches that mask real issues. Before implementing any fix, complete root cause investigation and hypothesis testing phases. Verify that your proposed solution addresses the actual problem source, not just the symptom. This disciplined workflow ensures fixes stick and prevents the cycle of temporary patches that create technical debt and future failures.
SKILL.md
rendered from the published skill — quoted content, verbatim
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.
Violating the letter of this process is violating the spirit of debugging.
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
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 1 file
skills/software-development/systematic-debugging/SKILL.md