debug

Trace bugs to their root cause using a four-phase investigation framework.

Updated Feb 5, 2026
One-click install
npx skills add https://github.com/mguinada/ai-coding-toolkit --skill debug-mguinada
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: debug
Source: https://github.com/mguinada/ai-coding-toolkit/tree/main/skills/debug
Command: npx skills add https://github.com/mguinada/ai-coding-toolkit --skill debug-mguinada

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Systematic bug investigation using a root-cause-first methodology helps teams quickly identify the true origin of failures, reducing wasted effort on superficial fixes and ensuring fixes address the real issue.

Core Features & Use Cases

  • Phase-driven debugging workflow that guides root-cause investigation through four phases: Phase 1 Root Cause Investigation, Phase 2 Pattern Analysis, Phase 3 Hypothesis and Testing, Phase 4 Implementation.
  • Backward tracing and data-flow analysis to locate the origin of errors, avoiding premature guards at symptoms.
  • References-driven hardening: linkages to defense-in-depth and root-cause tracing techniques to improve future resilience.
  • Use cases include reproducing errors, tracing failures in multi-component systems, debugging flaky tests, diagnosing performance regressions, and investigating unexpected output.

Quick Start

Describe a reproducible bug scenario and ask the system to apply root-cause tracing to identify the origin before proposing a fix.

Frequently Asked Questions about debug

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

FAQPage Schema
What is root-cause debugging and when do I need it for multi-component systems?

Root-cause debugging identifies the true origin of failures in multi-component systems where errors propagate across modules. You need it when superficial fixes fail to resolve issues like performance regressions or flaky tests, ensuring the actual problem is addressed.

How do I trace errors backward to find the root cause of a bug?

Trace errors backward by applying data-flow analysis to locate where failures originate, avoiding premature guards at symptoms. This systematic bug investigation uses pattern analysis and hypothesis testing to confirm the root cause before implementation.

What's the best way to debug flaky tests and performance regressions systematically?

The best way to debug flaky tests and performance regressions is using a phase-driven workflow: investigate root cause, analyze patterns, test hypotheses, then implement fixes. This prevents wasted effort on superficial patches for complex system issues.

How do I start a bug investigation using a root-cause-first methodology?

Start a root-cause-first bug investigation by describing a reproducible bug scenario. The system applies backward tracing through four phases—root cause investigation, pattern analysis, hypothesis testing, and implementation—to identify the origin before proposing a fix.

Does root-cause debugging work for tracing failures across multiple modules?

Yes, root-cause debugging applies to multi-component systems where errors propagate across modules. It uses references-guided tracing techniques and data-flow analysis to follow failures backward to their origin, avoiding premature guards at symptom points.

When should I not use root-cause tracing for bug investigation?

Avoid root-cause tracing for simple, isolated bugs where the origin is immediately obvious. It is designed for complex scenarios like flaky tests, performance regressions, and multi-component failures where errors propagate and superficial fixes are insufficient.