systematic-debugging

Enforce root-cause investigation before applying fixes in a four-phase debugging workflow.

103|21|Updated Feb 12, 2026

Search Tags:#debugging #root cause analysis #test failures #hypothesis testing #incident response #guardrails #tdd workflow

Ready to run

npx skills add https://github.com/archibate/dotfiles-opencode --skill systematic-debugging-archibate

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/archibate/dotfiles-opencode/tree/main/skills/systematic-debugging
Command: npx skills add https://github.com/archibate/dotfiles-opencode --skill systematic-debugging-archibate

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) and assets (resource) components.

What problem does it solve?

It prevents wasted time and repeated regressions by stopping you from applying symptom-based changes when a bug’s true cause hasn’t been identified yet.

Core Features & Use Cases

ALWAYS root-cause first: Enforces the iron law that no fixes happen before Phase 1 investigation is complete.
Four-phase debugging workflow: Guides you through Root Cause Investigation → Pattern Analysis → Hypothesis & Testing → Implementation, with explicit rules to stop and re-analyze when failures occur.
Anti-rationalization guardrails: Provides red flags for when you’re tempted to skip steps, add multiple changes, or keep retrying after repeated unsuccessful fixes.
Works for real scenarios: Applicable to test failures, production bugs, unexpected behavior, performance/build/integration issues, especially under time pressure.

Quick Start

Tell your AI: “Use systematic-debugging to diagnose this issue—follow Phase 1 first, then only proceed to Phase 2–4 after you’ve formed and tested a single root-cause hypothesis.”

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 a test failure instead of just fixing symptoms?▼

To find the root cause of a test failure, you must enforce an investigation phase that gathers evidence and forms a single hypothesis before making any code changes. This prevents repeated regressions caused by applying symptom-based fixes.

What is the best way to debug production bugs under time pressure?▼

The best way to debug production bugs under time pressure is to follow a four-phase workflow: root cause investigation, pattern analysis, single-hypothesis testing, and implementation. This enforces evidence gathering before applying fixes.

Why do my quick fixes keep failing and causing repeated regressions?▼

Quick fixes keep failing and causing repeated regressions because they address symptoms without identifying the underlying root cause. You need to stop and re-analyze the issue using evidence gathering and hypothesis testing before implementing changes.

How do I carry out hypothesis testing for unexpected behavior and build failures?▼

To carry out hypothesis testing for unexpected behavior and build failures, isolate a single root-cause hypothesis, test it against gathered evidence, and write a failing test first before proceeding to the actual implementation fix.

When should I stop and re-analyze during incident response debugging?▼

You should stop and re-analyze during incident response debugging after unsuccessful fix attempts. Guardrails mandate stopping when you are tempted to skip steps, add multiple changes, or keep retrying fixes after repeated failures.