systematic-debugging

Enforces a four-phase root-cause debugging workflow for software failures.

Updated Mar 7, 2026

Search Tags:#testing #debugging #defense-in-depth #phases #root-cause #systematic-debugging

Ready to run

npx skills add https://github.com/randoneering/nix-flake-mirror --skill systematic-debugging-randoneering

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/randoneering/nix-flake-mirror/tree/main/home/programs/opencode/skills/systematic-debugging
Command: npx skills add https://github.com/randoneering/nix-flake-mirror --skill systematic-debugging-randoneering

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Engineers often chase quick fixes under time pressure, which masks root causes and creates more bugs. This skill enforces a disciplined, four-phase debugging process to ensure root-cause investigation before proposing fixes.

Core Features & Use Cases

Phase-guided workflow: Phase 1 Root Cause Investigation, Phase 2 Pattern Analysis, Phase 3 Hypothesis & Testing, Phase 4 Implementation, with mandatory progression rules.
Built-in anti-shortcut guidance and defense-in-depth concepts to catch edge cases and prevent regressions.
Use cases include production incidents, flaky tests, and complex multi-component systems where symptoms mislead quick fixes.

Quick Start

Follow the four-phase debugging workflow on any bug or failure before attempting fixes.

Frequently Asked Questions about systematic-debugging

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

FAQPage Schema

What is a systematic debugging workflow for finding root causes?▼

Systematic debugging is a four-phase workflow enforcing root-cause investigation before any fixes. It requires gathering evidence, analyzing patterns, testing minimal hypotheses, and implementing validated solutions to prevent symptom-masking quick fixes.

How do I fix flaky tests without masking the root cause?▼

To fix flaky tests without masking root causes, follow a disciplined four-phase workflow: investigate root causes, analyze patterns, test minimal hypotheses, and implement fixes. This ensures traceable outcomes and prevents regressions in complex systems.

When should I use a root-cause investigation process for production incidents?▼

Use root-cause investigation for production incidents, test failures, and unexpected behavior in multi-component systems where symptoms mislead quick fixes. It enforces evidence gathering and hypothesis testing before proposing any code changes.

What is the best way to debug complex multi-component software systems?▼

The best way to debug complex systems is a phase-guided workflow with mandatory progression rules. It enforces pattern analysis, minimal hypothesis testing, and defense-in-depth validation to catch edge cases and ensure robust, traceable outcomes.

Does systematic debugging prevent regressions during incident response?▼

Yes, systematic debugging prevents regressions by applying defense-in-depth concepts and mandatory phase completion. It requires evidence gathering and hypothesis validation before implementation, ensuring fixes address actual root causes rather than symptoms.

Why does chasing quick fixes create more bugs in software engineering?▼

Chasing quick fixes under time pressure masks root causes and creates more bugs because it skips evidence gathering and pattern analysis. A disciplined four-phase debugging process ensures root-cause investigation before any fix is implemented.