Agent Skill
Systematic Debugging
Root cause analysis methodology requiring systematic hypothesis testing and evidence collection before attempting any fixes
What is Systematic Debugging?
This skill enforces a disciplined debugging methodology where agents must identify root causes through systematic investigation before attempting any fixes. The approach mandates the Iron Law: no fixes without root cause analysis, as symptom fixes waste time and create new bugs. The skill covers gathering evidence through logs, error messages, and reproduction steps, forming testable hypotheses about failure mechanisms, designing experiments to validate or refute each hypothesis, eliminating possibilities systematically, identifying the true root cause with evidence, understanding why the bug occurred and why it was not caught earlier, then implementing a targeted fix that addresses the cause rather than symptoms. The agent learns to resist the temptation of quick patches, understanding that random fixes and guessing waste far more time than structured investigation. The skill establishes boundaries between symptoms that manifest and underlying causes, between reproducing a bug and understanding its mechanism, and between fixes that address symptoms versus those that eliminate root causes. Trade-offs include the time investment in systematic investigation versus pressure for quick fixes, the granularity of hypothesis testing, and knowing when sufficient evidence exists to confirm root cause. The skill emphasizes that debugging is a scientific process requiring reproducibility, hypothesis testing, and verification.
Key capabilities
Iron Law enforcement against symptom fixes
Absolutely prohibits attempting fixes without identifying root cause, preventing the common antipattern of treating symptoms while underlying issues persist
Hypothesis-driven investigation
Structures debugging as a scientific process of forming testable hypotheses about failure mechanisms, designing experiments to validate them, and systematically eliminating possibilities
Evidence-based root cause identification
Requires collecting concrete evidence—logs, error messages, reproduction steps, state inspection—to prove the root cause rather than relying on assumptions or intuition
Prevention analysis and learning
Mandates understanding not just why the bug occurred, but why it was not caught earlier, leading to improvements in testing, code review, or development practices
Use cases
Production incident investigation
Diagnose production failures by gathering logs and metrics, forming hypotheses about potential causes, testing each hypothesis against evidence, identifying the root cause, and implementing a fix that prevents recurrence
Flaky test analysis
Investigate intermittent test failures by reproducing the failure consistently, analyzing timing and state variations, identifying race conditions or environmental dependencies, and fixing the underlying instability
Performance degradation debugging
Diagnose performance issues by profiling to identify hotspots, forming hypotheses about bottlenecks, validating each through targeted measurements, and optimizing the actual constraint rather than guessing
Integration failure diagnosis
Debug failures at system boundaries by isolating which component fails, examining message formats and protocols, testing hypotheses about mismatches, and correcting the actual incompatibility