systematic-debugging

Trace data flow and test hypotheses to resolve root causes of software failures.

15|Updated Feb 14, 2026
One-click install
npx skills add https://github.com/mahoushoujyo-eee/eshell --skill systematic-debugging-mahoushoujyo-eee
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/mahoushoujyo-eee/eshell/tree/main/.codex/skills/systematic-debugging
Command: npx skills add https://github.com/mahoushoujyo-eee/eshell --skill systematic-debugging-mahoushoujyo-eee

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill prevents guesswork, symptom fixes, and repeated rework by guiding you through a disciplined process for identifying and resolving the root cause of technical problems.

Core Features & Use Cases

  • Four-Phase Investigation: Progress through root cause investigation, pattern analysis, hypothesis testing, and implementation.
  • Evidence-Driven Debugging: Reproduce failures, inspect recent changes, trace data flow, compare working examples, and gather diagnostic evidence across system boundaries.
  • Safety and Reliability Guardrails: Enforce single-hypothesis testing, failing-test creation, incremental fixes, verification, and architectural review after repeated failures.
  • Use Case: Apply the Skill to a flaky asynchronous test by replacing guessed delays with condition-based waiting and tracing the underlying state-update failure.

Quick Start

Use the systematic debugging skill to investigate this failure, identify its root cause, and propose a verified fix only after completing the investigation.

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 fixing symptoms?

To find the root cause of flaky test failures, you must reproduce the failure, trace data flow across system boundaries, and test a single hypothesis at a time before applying an incremental fix. This replaces guessed delays with condition-based waiting and evidence-driven debugging.

What is the best way to investigate deep call-stack errors and integration failures?

The best way to investigate deep call-stack errors and integration failures is through systematic data-flow tracing and working-example comparison across multi-component software systems. This process isolates the exact state-update failure causing the integration breakdown.

How do I debug non-reproducible bugs and unexpected behavior in complex systems?

Debugging non-reproducible bugs requires gathering diagnostic evidence across system boundaries and inspecting recent changes. You systematically trace data flow and compare working examples to expose the hidden state conditions triggering the unexpected behavior.

What should I do when my bug fixes keep failing and the issue reoccurs?

When bug fixes repeatedly fail, you must stop guessing and conduct an architectural review. Enforce single-hypothesis testing and create failing tests to verify the root cause before attempting another incremental implementation.

When should I use hypothesis testing for bug investigation?

You should use hypothesis testing for bug investigation whenever you face test failures, build failures, or performance problems. It enforces evidence gathering and failing-test creation to ensure you resolve the actual root cause rather than applying symptom fixes.