systematic-debugging

Enforce root-cause investigation before fixes using a four-phase debugging process.

Updated Dec 11, 2024
One-click install
npx skills add https://github.com/huaxel/dotfiles --skill systematic-debugging-huaxel
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/huaxel/dotfiles/tree/main/skills/systematic-debugging
Command: npx skills add https://github.com/huaxel/dotfiles --skill systematic-debugging-huaxel

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

The skill provides a disciplined, four-phase process to systematically debug bugs, ensuring root cause is found before fixes and preventing symptom-focused patches.

Core Features & Use Cases

  • Four-phase framework: Phase 1 Root Cause Investigation, Phase 2 Pattern Analysis, Phase 3 Hypothesis & Testing, Phase 4 Implementation.
  • Anti-patterns and strong guardrails ensuring you never fix symptoms without evidence.
  • Clear references to root-cause-tracing.md, defense-in-depth.md, and related techniques for robust debugging.
  • Use across test failures, production issues, flaky tests, and complex system bugs with defensible remediation.

Quick Start

Begin with Phase 1: root-cause investigation, then progress through Phase 2–4, using the accompanying reference documents to reinforce each step.

Frequently Asked Questions about systematic-debugging

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
What is systematic debugging and how does it prevent symptom fixes?

Systematic debugging enforces root-cause investigation before applying fixes, preventing symptom-driven patches. It uses a four-phase process with explicit rules and defense-in-depth validation to ensure reliable resolution across codebases, CI pipelines, and production scenarios.

How do I debug software bugs step by step using root cause analysis?

Debug software bugs by following a four-phase process: Phase 1 Root Cause Investigation, Phase 2 Pattern Analysis, Phase 3 Hypothesis & Testing, and Phase 4 Implementation. This framework ensures you find root causes before fixes using explicit rules and anti-patterns.

Can I use this systematic debugging framework for flaky tests and CI pipeline failures?

Yes, this systematic debugging framework applies to test failures, flaky tests, production issues, and complex system bugs. It provides defensible remediation across codebases and CI pipelines by enforcing root-cause investigations before fixes.

What's the best way to stop applying symptom patches when fixing production bugs?

The best way to stop symptom patches is applying strong guardrails and anti-patterns during root-cause debugging. This enforces evidence-based hypothesis testing before implementation, eliminating symptom-focused patches through defense-in-depth validation.

Why does my debugging process keep fixing symptoms instead of finding the root cause?

Your debugging process fixes symptoms because it lacks enforced root-cause investigation phases. By applying a four-phase framework with explicit anti-patterns and defense-in-depth validation, you ensure evidence is found and tested before any implementation begins.

When should I not use a systematic four-phase debugging approach?

You should reconsider systematic four-phase debugging when immediate mitigations are required for critical production incidents. However, defensible remediation still requires root-cause investigation afterward to prevent recurring symptom-driven patches and ensure reliable resolution.