systematic-debugging

Name: systematic-debugging
Availability: InStock
Author: miptah21

Guide root-cause debugging through four phases before implementing fixes.

2|Updated Apr 8, 2026

Search Tags:#architecture #debugging #root cause #verification #test failures #hypothesis testing #incident response

Ready to run

npx skills add https://github.com/miptah21/skills --skill systematic-debugging-miptah21

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/miptah21/skills/tree/main/.agents/skills/systematic-debugging
Command: npx skills add https://github.com/miptah21/skills --skill systematic-debugging-miptah21

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill prevents wasted time and recurring bugs by enforcing root-cause investigation before any code or configuration changes.

Core Features & Use Cases

Root-cause first debugging (Iron Law): mandates “NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST” and blocks symptom-whack-a-mole.
Four-phase workflow: Phase 1 investigation, Phase 2 pattern analysis, Phase 3 hypothesis testing, and Phase 4 implementation with verification and explicit failure handling.
Pressure- and failure-resistant guardrails: includes “Red Flags - STOP and Follow Process”, rules for “failed first fix”, and guidance to “question architecture” after 3+ failed fixes.
Multi-component evidence gathering: provides a boundary-by-boundary diagnostic approach and includes guidance for tracing through deep call stacks using root-cause-tracing.md.

Quick Start

Use systematic debugging when you hit any bug or unexpected behavior, and follow the Four Phases in order until you can implement a root-cause fix.

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 test failures instead of just patching symptoms?▼

Root cause debugging requires completing a full investigation phase before proposing any fixes, enforcing evidence gathering at component boundaries to prevent symptom-only patches and recurring test failures.

What is the best way to debug a production incident across multi-layer systems?▼

Debugging production incidents across multi-layer systems requires boundary-by-boundary evidence gathering and hypothesis testing to trace failures through deep call stacks before applying any configuration changes.

How do I stop thrashing when my first fix for an unexpected error fails?▼

When a first fix fails, systematic debugging applies STOP rules to halt thrashing, requiring a single hypothesis with minimal testing and explicit architecture reassessment after three or more failed fixes.

When should I question architecture during incident response?▼

Questioning architecture during incident response becomes necessary after repeated fix failures, specifically triggering a mandatory architecture reassessment once three or more proposed fixes fail to resolve the unexpected behavior.

Do I need to create a failing test before implementing a bug fix?▼

Creating a failing test before implementation is required, serving as verification that the root cause hypothesis is correct and ensuring the subsequent fix addresses the actual failure rather than masking it.