debug-root-cause

Diagnose bugs and test failures through evidence-based root-cause investigation workflows.

Updated Jul 3, 2026
One-click install
npx skills add https://github.com/mnazaal/dotfiles --skill debug-root-cause-mnazaal
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: debug-root-cause
Source: https://github.com/mnazaal/dotfiles/tree/main/.agents/skills/debug-root-cause
Command: npx skills add https://github.com/mnazaal/dotfiles --skill debug-root-cause-mnazaal

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Debugging often devolves into guessing fixes, patching symptoms, or stacking multiple changes at once, which wastes time and hides the real defect. This Skill enforces a disciplined root-cause investigation process so bugs, test failures, crashes, and flaky behavior are fixed at their source with evidence. ## Core Features & Use Cases - Repro Loop Construction: Builds a fast, deterministic, red-capable reproduction loop from failing tests, CLI invocations, replayed inputs, bisection harnesses, or differential runs before any hypothesis is formed. - Hypothesis Discipline: Generates ranked falsifiable hypotheses, probes one variable at a time, and enforces reassessment rules after failed fixes to stop symptom-patching. - Environment & State Diagnosis: Handles cross-environment failures, stale caches, and non-deterministic bugs with comparison runs, state invalidation checks, and reproduction-rate amplification. - Use Case: A CI test fails only in the container but passes locally. The Skill guides running the same artifact in both environments, isolating the boundary difference in one step, then stating the confirmed root cause with evidence before handing a minimal fix plan to development. ## Quick Start Ask the agent to investigate why the failing test or command broke and find the root cause before proposing any fix.

Frequently Asked Questions about debug-root-cause

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

FAQPage Schema
How do I find the root cause of a failing test?▼

Start by capturing the exact symptom: command, output, expected versus observed behavior, and recent changes. Then build a deterministic reproduction loop that goes red on the symptom before forming hypotheses, and probe one variable at a time until evidence confirms the cause.

How to debug a bug that only happens in CI but not locally?▼

Run the same artifact in both environments and compare before theorizing about which difference matters. One comparison between container and host or CI and local localizes the fault to the boundary in a single step, before any hypothesis is needed.

Why does my code fail today when nothing changed since yesterday?▼

Unchanged code with new failures usually means stale state, not broken code. Suspect preprocessing or JIT caches, lockfiles mismatched with the virtual environment, stale output directories, or half-written checkpoints, and clear them one at a time to isolate the cause.

What should I do when the first fix does not work?▼

Stop and reassess the hypothesis before trying another fix rather than stacking patches. If three fixes fail, stop patching entirely and map shared state, hidden coupling, environment differences, and assumptions instead.

How do I debug flaky or non-deterministic test failures?▼

Aim for a higher reproduction rate rather than a clean repro. Loop the trigger, parallelize execution, add stress, and narrow timing windows until the failure is frequent enough to probe systematically.