systematic-debugging

Guide root-cause debugging through evidence gathering, hypothesis testing, and verified fixes.

Updated Apr 30, 2026
One-click install
npx skills add https://github.com/koseki2580/skills --skill systematic-debugging-koseki2580
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/koseki2580/skills/tree/main/skills/systematic-debugging
Command: npx skills add https://github.com/koseki2580/skills --skill systematic-debugging-koseki2580

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill prevents wasted time on random fixes by enforcing a disciplined root-cause-first debugging workflow for technical failures and unexpected behavior.

Core Features & Use Cases

  • Four-phase root-cause workflow: Root cause investigation, pattern analysis, hypothesis testing, then implementation with verification.
  • Evidence-first in complex systems: Adds diagnostic instrumentation across component boundaries (e.g., CI → build → signing, API → service → database) to identify where it breaks.
  • Guardrails against bad habits: Strong red flags that require you to stop and return to Phase 1 when you start guessing, bundling changes, or piling on fixes.
  • Architecture re-evaluation trigger: After 3+ failed fix attempts, it explicitly tells you to question architecture and re-expand causes using fishbone-analysis.

Quick Start

Use systematic-debugging when you hit a test failure or unexpected production behavior and follow the four phases until the root cause is fixed and the fix is verified.

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 guessing random fixes?

To find the root cause of test failures, you need a systematic debugging workflow that enforces evidence gathering, pattern analysis, and hypothesis testing before implementing any fixes. This approach prevents wasted time on random changes by requiring strict phase ordering with stop rules.

What is the best way to debug production incidents across multiple components?

The best way to debug production incidents across multiple components is to add diagnostic instrumentation across boundaries, such as from API to service to database, to gather evidence and identify exactly where the failure occurs before forming a hypothesis.

How do you perform hypothesis testing when debugging unexpected behavior?

Hypothesis testing for unexpected behavior requires applying minimal-change tests to verify your assumptions. You must enforce strict stop rules that prevent bundling changes or piling on fixes, ensuring each hypothesis is tested in isolation.

When should I re-evaluate architecture during root cause analysis?

You should re-evaluate architecture during root cause analysis after three or more failed fix attempts. This explicit trigger tells you to stop guessing and question the architecture, re-expanding potential causes using fishbone-analysis techniques.

Can I use systematic debugging for build and integration problems?

Yes, you can use systematic debugging for build and integration problems. The workflow applies to both single-path and multi-component failures, requiring evidence gathering across CI pipelines and build boundaries to identify the exact failure point.

Why does my debugging process keep thrashing without finding a solution?

Your debugging process keeps thrashing because of bad habits like guessing, bundling changes, or piling on fixes without evidence. Strong red flags and guardrails require you to stop and return to root cause investigation whenever these habits emerge.