debuglisted

# Debug Debugging is hypothesis-driven investigation, not random exploration. The goal is to find the root cause — not just a fix that makes the symptom disappear. ## Phase 1: Frame the problem Before touching any code, establish: 1. **What is the expected behavior?** State it precisely. 2. **What is the actual behavior?** Include exact error messages, stack traces, or wrong outputs — not summaries. 3. **What changed recently?** A regression almost always has a cause. Ask if anything was deployed, upgraded, or modified before the symptom appeared. 4. **Is the problem reproducible?** If yes, under what conditions exactly? If intermittent, what's the pattern? Don't skip this. Jumping to code before framing the problem wastes time and often leads to fixing the wrong thing. ## Phase 2: Form a hypothesis State the most likely root cause as a falsifiable claim: > "I think X is happening because Y." A good hypothesis is specific enough that you can design a test to disprove it. If you can't think of such a test, the hypothesis is too vague — narrow it down. Start with the simplest explanation consistent with the evidence (Occam's razor). Common culprits, roughly in order of likelihood: - Wrong assumption about input data or state - Off-by-one, boundary condition, or null/undefined - Race condition or ordering dependency - Config or environment difference between working and broken context - A dependency behaving differently than expected (version change, API contract) - L