debugging-systematically

Guide engineers through a four-phase root-cause debugging process.

3|Updated Jan 22, 2026
One-click install
npx skills add https://github.com/falconnt/windsurf-skills --skill debugging-systematically
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: debugging-systematically
Source: https://github.com/falconnt/windsurf-skills/tree/main/debugging-systematically
Command: npx skills add https://github.com/falconnt/windsurf-skills --skill debugging-systematically

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps teams avoid guesswork by guiding engineers through a formal, four-phase debugging process to identify and fix root causes rather than symptoms.

Core Features & Use Cases

  • Four Phases: Root Cause Investigation, Pattern Analysis, Hypothesis & Testing, and Implementation with mandatory progression.
  • Defense-in-Depth: Encourages multi-layer validation to prevent regression and data issues.
  • Context & References: Includes reference materials like root-cause-tracing and defense-in-depth guides to support engineers during debugging.
  • Usage Scenarios: Useful for on-call incidents, CI failures, flaky tests, and complex system bugs.

Quick Start

Use this skill when you face any bug, test failure, or unexpected behavior. Load the SKILL.md, read the overview, perform Phase 1 before proposing fixes, and reference the supplemental materials as needed.

Frequently Asked Questions about debugging-systematically

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

FAQPage Schema
What is systematic root-cause debugging and when should I use it?

Systematic root-cause debugging is a formal, four-phase process to identify and fix underlying causes rather than symptoms. Use it during on-call incidents, CI failures, flaky tests, and complex system bugs to eliminate guesswork.

How do I debug flaky tests and CI failures systematically?

To debug flaky tests and CI failures systematically, follow a mandatory four-phase progression: root-cause investigation, pattern analysis, hypothesis testing, and implementation. This enforces structured validation before proposing any fixes.

What is the best way to handle on-call incidents without guessing?

The best way to handle on-call incidents without guessing is applying a defense-in-depth debugging process. This enforces multi-layer validation across root-cause investigation, pattern analysis, hypothesis testing, and implementation to prevent regressions.

Does this debugging process require any specific testing frameworks or dependencies?

No, this systematic debugging process requires no specific testing frameworks or dependencies. It is a phase-driven methodology applicable across development, QA, and CI environments to resolve unexpected behavior.

How does a defense-in-depth approach help prevent bug regressions?

A defense-in-depth approach helps prevent bug regressions by encouraging multi-layer validation during the debugging process. This ensures that root causes are thoroughly tested across hypotheses before implementation, avoiding data issues and recurring failures.

Why should I not fix bugs immediately upon seeing unexpected behavior?

You should not fix bugs immediately because skipping root-cause investigation often addresses symptoms rather than the actual fault. A systematic four-phase debugging process ensures you trace and validate the true root cause before implementation.