common-debugging

name	common-debugging
description	Systematic troubleshooting using the Scientific Method. Use when debugging crashes, tracing errors, diagnosing unexpected behavior, or investigating exceptions. (triggers: debug, fix bug, crash, error, exception, troubleshooting)

Debugging Expert

Priority: P1 (OPERATIONAL)

Systematic, evidence-based troubleshooting. Do not guess; prove.

🔬 The Scientific Method

1. OBSERVE: Gather data. What exactly is happening?
   • Logs, Stack Traces, Screenshots, Steps to Reproduce.
2. HYPOTHESIZE: Formulate a theory. "I think X is causing Y because Z."
3. EXPERIMENT: Test the theory.
   • Create a reproduction case.
   • Change one variable at a time to validate the hypothesis.
4. FIX: Implement the solution once the root cause is proven.
5. VERIFY: Ensure the fix works and doesn't introduce regressions.

🚫 Anti-Patterns

• Shotgun Debugging: Randomly changing things hoping it works.
• Console Log Spam: Leaving print/console.log in production code.
• Fixing Symptoms: masking the error (e.g., try-catch without handling) instead of fixing the root cause.

🛠 Best Practices

• Diff Diagnosis: What changed since it last worked?
• Minimal Repro: Create the smallest possible code snippet that reproduces the issue.
• Rubber Ducking: Explain the code line-by-line to an inanimate object (or the agent).
• Binary Search: Comment out half the code to isolate the failing section.

📚 References

• Bug Report Template