skills.rest
miptah21
miptah21COMMUNITY
Explore all skills by this author →
GitHub

systematic-debugging

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
One-click install
npx skills add https://github.com/miptah21/skills --skill systematic-debugging-miptah21
Or copy as Structured Prompt for Agent▼
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.

Related Skills

Explore More Software Engineering Skills→
mordonezmordonez
3

troubleshooting-liferay

Diagnose failing local Liferay runtimes using ldev doctor, status, and logs.

Community
Intermediate
bidahbidah
28

systematic-debugging

Diagnose root causes through evidence gathering and single-hypothesis testing before fixes.

Community
Advanced
mkurmanmkurman
321

systematic-debugging

Identify root causes of bugs across complex systems using a four-phase workflow.

Community
Advanced
dogekikidogekiki

systematic-debugging

Apply a four-phase framework to identify and resolve root causes of technical issues.

Community
Advanced