systematic-debugging

Guide systematic root-cause debugging through four phases before proposing fixes.

7|2|Updated Nov 30, 2025
One-click install
npx skills add https://github.com/ajbmachon/ajbm-skills --skill systematic-debugging-ajbmachon
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/ajbmachon/ajbm-skills/tree/main/plugins/development-skills/skills/systematic-debugging
Command: npx skills add https://github.com/ajbmachon/ajbm-skills --skill systematic-debugging-ajbmachon

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill prevents wasted time and new bugs by forcing a disciplined root-cause-first debugging process before proposing any fixes.

Core Features & Use Cases

  • Four-phase debugging framework: root cause investigation, pattern analysis, hypothesis testing, then implementation.
  • Pressure-resistant guardrails: explicitly prevents symptom-chasing and “quick fix” rationalizations, especially during emergencies.
  • Evidence-first handling for complex systems: instructs how to gather diagnostics across component boundaries and trace data flow back to the earliest incorrect source.

Quick Start

When you hit any bug, test failure, or unexpected behavior, follow the four phases and do not attempt any fixes until Phase 1 (root cause investigation) is complete.

Frequently Asked Questions about systematic-debugging

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

FAQPage Schema
How do I find the root cause of a test failure or production incident instead of guessing at fixes?

Root cause debugging requires completing a thorough investigation phase before any fixes, gathering evidence across component boundaries and tracing data flow back to the earliest incorrect source. This prevents symptom-chasing and “quick fix” rationalizations during pressure-filled incidents.

What is the best way to debug multi-component system failures where evidence crosses boundaries?

Multi-component system debugging uses an evidence-first approach, gathering diagnostics across boundaries to trace data flow back to the earliest incorrect source. This four-phase framework ensures you form a single hypothesis before implementing any fix.

How do I systematically debug an unexpected technical behavior or build problem?

Systematic debugging follows a four-phase framework: root cause investigation, pattern analysis, hypothesis testing, then implementation via a failing test and single-root fix. You must complete Phase 1 prior to any fixes to avoid wasted time and new bugs.

When should I use hypothesis testing for debugging instead of trying quick fixes?

Hypothesis testing is necessary when you face any bug, test failure, or unexpected behavior and want to prevent new bugs. Pressure-resistant guardrails explicitly prevent symptom-chasing, requiring you to form a single hypothesis and implement via a failing test.

Can I use this systematic debugging approach for both production outages and integration failures?

Yes, this systematic root-cause debugging applies to production outages, integration failures, and performance or build problems. It handles complex systems by requiring evidence gathering across component boundaries before proposing any fixes.

Why does my debugging process keep introducing new bugs when I apply quick fixes?

Quick fixes introduce new bugs because they chase symptoms rather than finding the root cause. A disciplined root-cause-first debugging process forces you to complete investigation, pattern analysis, and hypothesis testing before implementing a single-root fix via a failing test.