systematic-debugging

Diagnose software bug root causes through evidence gathering and hypothesis testing.

Updated Mar 31, 2026
One-click install
npx skills add https://github.com/DFly7/iOS-FastAPI-Supabase-AI --skill systematic-debugging-dfly7
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/DFly7/iOS-FastAPI-Supabase-AI/tree/main/.agents/skills/systematic-debugging
Command: npx skills add https://github.com/DFly7/iOS-FastAPI-Supabase-AI --skill systematic-debugging-dfly7

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Random fixes and guesswork lead to wasted time, recurring regressions, and brittle code; this skill enforces a disciplined approach so you fix the true source of bugs rather than symptoms.

Core Features & Use Cases

  • Four-phase workflow: explicit phases for Root Cause Investigation, Pattern Analysis, Hypothesis & Testing, and Implementation to prevent premature fixes.
  • Evidence-driven diagnosis: instructions for reproducing issues, multi-component instrumentation, and backward tracing to locate the original trigger.
  • Pressure-resistant rules: anti-patterns, stop-gates, and failure-mode guidance to resist time pressure and authority bias.
  • Supporting techniques: condition-based waiting, defense-in-depth validation, and bisection helpers to find polluting tests or flaky behaviors.
  • Use cases: reproducing and fixing flaky tests, diagnosing production errors, tracing deep call-stack failures, and avoiding shotgun fixes during emergencies.

Quick Start

Run the systematic-debugging skill to investigate a failing test, gather cross-component evidence, form a single hypothesis, and produce a minimal failing test plus a targeted 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 flaky tests instead of just treating symptoms?

To find the root cause of flaky tests, you must enforce consistent reproduction and gather multi-component evidence before making any code changes. This approach uses backward tracing to locate the original trigger, ensuring you fix the true source of bugs rather than applying random shotgun fixes.

What is the best way to debug production incidents without guessing?

The best way to debug production incidents is through evidence-driven diagnosis and single-hypothesis testing. By applying pressure-resistant rules and stop-gates, you resist time pressure and authority bias, ensuring reliable diagnosis through minimal changes and targeted fixes.

How do I stop recurring regressions caused by premature bug fixes?

To stop recurring regressions from premature bug fixes, follow a four-phase workflow: Root Cause Investigation, Pattern Analysis, Hypothesis & Testing, and Implementation. Creating a failing test before implementing fixes prevents guesswork and ensures the true source of bugs is resolved.

Can I use systematic debugging for CI build breakages and integration errors?

Yes, you can use systematic debugging for CI build breakages and integration errors. It applies to any technical issue requiring reliable diagnosis, utilizing bisection helpers to find polluting tests and condition-based waiting to trace deep call-stack failures effectively.

What are the limitations of guesswork when tracing deep call-stack failures?

Guesswork fails when tracing deep call-stack failures because it leads to wasted time and brittle code. Without multi-component instrumentation and backward tracing to locate the original trigger, random fixes only mask symptoms rather than resolving the underlying root cause.