systematic-debugging

---

name: systematic-debugging description: Use when encountering bugs, test failures, or unexpected behavior - ensures root cause understanding before attempting fixes

Core principle: If you can't explain WHY it's broken, you're not ready to fix it. Every fix must address a specific, understood root cause.

Work to reproduce the issue reliably. If you can't trigger it consistently, gather more data before proposing solutions. Document the exact steps that trigger the failure.

Check what changed recently. Review commits, new dependencies, configuration changes, environmental differences. Most bugs correlate with recent changes.

When multiple components interact, add diagnostic output at each boundary to identify which component fails. This narrows the investigation to the specific failing layer.

When implementing a pattern, read reference implementations thoroughly. Understand their dependencies, settings, and environmental requirements.

When a hypothesis proves wrong, form a new one based on what you learned. Don't layer fixes on top of failed attempts.

Apply a single, focused fix that addresses the root cause. Resist bundling other improvements or refactoring.

Verify the fix resolves the issue without breaking other functionality.

These patterns suggest reconsidering the fundamental approach rather than continuing to patch symptoms.

These thoughts signal you're guessing rather than debugging systematically.

Systematic debugging finds and fixes the real problem. Random attempts waste time and create new issues.