systematic-debugging

Diagnose bugs by reproducing issues and testing single hypotheses.

1|Updated Mar 27, 2026

Search Tags:#debugging #diagnostics #instrumentation #triage #root-cause-analysis #flaky-tests #test-failure

Ready to run

npx skills add https://github.com/minfengyuan/harness-knowledge-base --skill systematic-debugging-minfengyuan

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/minfengyuan/harness-knowledge-base/tree/main/skills/systematic-debugging
Command: npx skills add https://github.com/minfengyuan/harness-knowledge-base --skill systematic-debugging-minfengyuan

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill enforces a disciplined, evidence-driven debugging workflow to prevent guesswork and repeated symptom-only fixes by guiding engineers to establish reproducible root causes before any remediation.

Core Features & Use Cases

Four-phase workflow: Structured phases for root cause investigation, pattern analysis, hypothesis testing, and implementation with explicit stop conditions.
Practical techniques & artifacts: Backward stack tracing, defense-in-depth validations, condition-based waiting, and a test bisection script to locate polluters.
Use cases: Diagnose failing or flaky tests, debug production incidents, investigate build or integration failures, and create minimal failing tests for CI validation.

Quick Start

Investigate the failing test by reproducing the issue, gather layered evidence, form and test a single hypothesis, create a minimal failing test, and propose one minimal 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 test failures instead of patching symptoms?▼

To find the root cause of flaky test failures, you must enforce reproducible reproduction, gather layered evidence, and test single-variable hypotheses before applying any fixes to avoid symptom-only patches.

What is the best way to systematically debug production incidents and integration failures?▼

Systematic debugging of production incidents requires a four-phase workflow: root cause investigation, pattern analysis, hypothesis testing, and implementation with explicit stop conditions to ensure evidence-driven remediation.

How do I locate flaky test polluters in a continuous integration pipeline?▼

You can locate flaky test polluters by creating a test bisection script to isolate the polluting tests, establishing minimal failing tests for CI validation, and applying condition-based waiting.

Why do my build errors keep recurring after applying immediate code fixes?▼

Build errors keep recurring because symptom-only fixes are applied without reproducible evidence. You need backward stack tracing and per-layer instrumentation to identify the actual root cause.

Does systematic root-cause analysis work for multi-component integration problems?▼

Yes, root-cause analysis works for multi-component integration problems by enforcing reproducible reproduction and defense-in-depth validation to trace failures across multiple system layers.

When should I use a single-variable hypothesis test during software diagnostics?▼

You should use single-variable hypothesis testing during software diagnostics when investigating complex failures to isolate exact triggers, ensuring your minimal fix addresses the verified root cause.