systematic-debugging

Identify root causes of bugs and test failures through structured investigation.

24|5|Updated Feb 28, 2026
One-click install
npx skills add https://github.com/yves-s/just-ship --skill systematic-debugging-yves-s
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/yves-s/just-ship/tree/main/skills/systematic-debugging
Command: npx skills add https://github.com/yves-s/just-ship --skill systematic-debugging-yves-s

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Systematic Debugging prevents wasted time and new bugs from random fixes by enforcing a disciplined process to discover root causes before any change is made. It turns guesswork into reproducible investigation so fixes address the true source of failures rather than symptoms.

Core Features & Use Cases

  • Four-phase process: Root cause investigation, pattern analysis, hypothesis/testing, and implementation with clear handoffs between phases.
  • Multi-component diagnostics: Guidance for instrumenting and logging across component boundaries to locate failures in distributed systems and CI pipelines.
  • Hypothesis-driven fixes and TDD: Emphasizes minimal-change experiments, requiring a single hypothesis and a failing test case before implementing fixes.
  • When to use: test failures, production incidents, build or integration errors, performance regressions, and any time quick guesses are tempting.

Quick Start

Use systematic-debugging to diagnose a failing test or production bug by reproducing it reliably, tracing data flow to locate the failing component, forming a single hypothesis, creating a minimal failing test, and then applying the smallest change to verify a 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 a failing integration test or production incident?

To find the root cause of a failing test or production incident, you must reproduce the issue reliably, trace data flow across component boundaries using diagnostic instrumentation, and form a single-variable hypothesis before making changes.

What is the best way to troubleshoot multi-component CI build failures without introducing new bugs?

Troubleshooting multi-component CI build failures requires gathering diagnostic evidence across component boundaries and validating a single hypothesis with a minimal failing test, ensuring the fix addresses the true source rather than just the symptoms.

How to debug unexpected behavior in distributed systems by applying test-driven development?

Debug unexpected behavior in distributed systems by reproducing the failure, isolating the failing component through logging, creating a minimal failing test case that confirms your hypothesis, and then applying the smallest possible code change.

Can I use systematic debugging for performance regressions and build errors, or is it only for unit test failures?

Yes, you can use systematic debugging for performance regressions, build errors, CI issues, and production incidents. The process enforces evidence gathering and hypothesis testing across any scenario where quick guesses might otherwise lead to incorrect fixes.

Why should I create a failing test before applying a fix during root cause analysis?

Creating a failing test before applying a fix ensures your root cause analysis is accurate and hypothesis-driven. It verifies that the identified issue is reproducible and prevents random code changes that often introduce new bugs.

When should I not use hypothesis-driven debugging for test failures?

You should not rely on quick guesses or skip hypothesis-driven debugging when facing test failures, build issues, or production incidents. Avoiding this disciplined process risks treating symptoms instead of root causes, leading to wasted time and new bugs.