systematic-debugging

Guide software failure debugging through error capture, reproduction, and data-flow tracing.

1|1|Updated May 3, 2026
One-click install
npx skills add https://github.com/matt-riley/agent-skills --skill systematic-debugging-matt-riley
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/matt-riley/agent-skills/tree/main/skills/systematic-debugging
Command: npx skills add https://github.com/matt-riley/agent-skills --skill systematic-debugging-matt-riley

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Systematic debugging provides a disciplined framework to identify the root cause of software failures by guiding you through error capture, reproducibility, data-flow tracing, and structured investigations.

Core Features & Use Cases

  • Phase-guided workflow: follows defined phases (root-cause investigation, pattern analysis, hypothesis testing, implementation) to converge on a minimal fix.
  • Observability & boundary tracing: emphasizes logging, state snapshots, and boundary data flow to locate where things go wrong.
  • Handoff & escalation: includes guardrails to escalate after 3 failed attempts and maintain a clear documentation trail.
  • Use Case: debugging a failing test or intermittent production issue after a commit.

Quick Start

Capture the full error output, reproduce the failure consistently, and follow the four debugging phases to identify the root cause before proposing any fix.

Frequently Asked Questions about systematic-debugging

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

FAQPage Schema
What is the best way to find the root cause of an intermittent production failure?

Root cause analysis for intermittent production failures requires systematically capturing full error outputs, reproducing the failure consistently, and tracing data flow across boundaries to pinpoint the exact defect.

How do I debug a failing test after a recent git commit?

Debugging a failing test after a commit requires capturing the full error output, reproducing the failure consistently, and following a phase-guided workflow of pattern analysis and hypothesis testing to identify the root cause before proposing a fix.

What steps should I follow to trace data flow and fix a software bug?

Tracing data flow to fix a bug follows a phase-guided workflow: capture errors, reproduce the failure, analyze patterns, test hypotheses, and implement a minimal verified fix while tracking observability and state snapshots at boundaries.

When should I escalate an intermittent failure that keeps defying reproduction?

You should escalate an intermittent failure after three failed debugging attempts, leveraging the built-in escalation guardrails to maintain a clear documentation trail and hand off the data-flow tracing investigation.

Does this systematic debugging workflow require specific environment setup?

This workflow requires clear error messages, access to recent code changes, and a defined boundary plan to effectively trace data flow across development, CI, and production environments.

How do I ensure a minimal and verified fix after finding a software bug?

To ensure a minimal and verified fix, follow the structured debugging phases of hypothesis testing and implementation, using checkpoints and boundary data flow tracing to verify the root cause is resolved without introducing changes.