root-cause-debugging

name	root-cause-debugging
description	Find the actual cause of bugs, failures, flaky tests, and regressions before proposing a fix. Use when: debugging runtime errors, CI failures, broken features, inconsistent behavior, or production incidents.
argument-hint	Describe the bug, failure, or symptom and any evidence you already have
user-invocable	true
disable-model-invocation	false

Root Cause Debugging

When to Use

• A bug is reproducible but the cause is unclear
• A test is failing or flaky and the failure mode is misleading
• A build passes locally but fails in CI
• A feature regressed after a recent change
• Logs, stack traces, or user reports point to a symptom but not the source

Approach

Debugging should converge on the smallest verified explanation for the failure. Do not jump from symptom to fix. Gather evidence, reproduce deliberately, trace the execution path, isolate the failing assumption, and only then recommend or implement a change.

Prefer evidence over intuition. Every hypothesis should be checked against logs, code paths, data shape, runtime environment, and recent changes.

Procedure

1. Define the symptom precisely and gather evidence.
2. Reproduce the issue with the shortest reliable path you can find.
3. Trace the execution path and test hypotheses one at a time.
4. Isolate the smallest verified explanation for the failure.
5. Fix and validate against the original reproduction.

Use workflow.md for the full investigation flow and stack-specific checks.

Output

Produce a concise debugging report with:

1. Symptom summary
2. Reproduction steps
3. Evidence reviewed
4. Root cause
5. Recommended or implemented fix
6. Validation performed
7. Residual risks or follow-up checks

Example Usage Prompts

• /root-cause-debugging -> "This React page only crashes after navigating back from checkout"
• /root-cause-debugging -> "Pytest passes locally but fails in CI with a database timeout"
• /root-cause-debugging -> "My JUCE plugin crackles only when automation is enabled"

Examples

See EXAMPLES.md for example prompts, expected investigation patterns, and output shapes.

References

• RULES.md - Shared investigation and validation standards
• workflow.md - Detailed investigation flow and stack-specific guidance