systematic-debugging

Guide root-cause discovery for technical bugs before proposing fixes.

Updated Jul 11, 2022
One-click install
npx skills add https://github.com/zhengfran/dotconfig --skill systematic-debugging-zhengfran
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/zhengfran/dotconfig/tree/main/tools/ai/agents/skills/systematic-debugging
Command: npx skills add https://github.com/zhengfran/dotconfig --skill systematic-debugging-zhengfran

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill prevents wasted time and recurring bugs by forcing you to locate the root cause of failures instead of applying symptom-based patches.

Core Features & Use Cases

  • Root-cause-first debugging: Enforces the Iron Law that no fixes happen until Phase 1 evidence is gathered.
  • Pressure-resistant process: Uses explicit stop conditions (especially when fixes fail or time pressure hits) to prevent rationalizations.
  • Phase-driven workflow: Provides a structured progression through investigation, pattern analysis, hypothesis/testing, and implementation/verification.
  • Supports debugging across layers: Includes guidance for multi-component systems and backward tracing when the bug appears deep in the call stack.

Use cases: test failures, production bugs, unexpected behavior, build/integration issues, and flaky systems where timing/races are likely.

Quick Start

Use the systematic-debugging skill to debug any failing test or unexpected behavior by following the four required phases and refusing to propose fixes until Phase 1 root-cause investigation is complete.

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

To find the root cause of flaky test failures, you must complete a Phase 1 investigation to gather evidence before proposing any fixes. This structured approach uses pattern analysis and single-hypothesis minimal testing to locate the actual source of the timing or race condition.

What is the best way to debug multi-component build or CI failures systematically?

The best way to debug multi-component build or CI failures is to follow a phase-driven workflow that enforces root-cause-first investigation. This process uses backward tracing when the bug appears deep in the call stack, ensuring you verify the root cause before implementing any fix.

How do I stop applying patches and actually verify a root cause for unexpected production bugs?

To stop applying patches and verify a root cause for unexpected production bugs, enforce the Iron Law of no fixes until Phase 1 evidence is gathered. You then use pattern analysis and minimal single-hypothesis testing to confirm the exact origin of the unexpected behavior.

What should I do when my debugging fixes keep failing under time pressure?

When debugging fixes keep failing under time pressure, you should use explicit stop conditions to prevent rationalizations. This pressure-resistant process requires halting repeated fix attempts, stepping back to complete root-cause investigation, and applying stop rules after consecutive failures.

Can I use systematic hypothesis testing for deep call-stack problems in integration tests?

Yes, you can use systematic hypothesis testing for deep call-stack problems in integration tests. The workflow provides specific guidance for multi-component systems, including backward tracing from deep runtime failures to isolate and verify the root cause before fixing.

Why do I need pattern analysis before fixing unexpected runtime behavior?

You need pattern analysis before fixing unexpected runtime behavior because it identifies failure trends across single-system and multi-component layers. This analysis is required during the phase-driven workflow to form a single, testable hypothesis that confirms the root cause and prevents recurring bugs.