Methodology from obra/superpowers (MIT)

Systematic Debugging

Core rule: find the root cause before writing any fix.

Phase 1 -- Root Cause Investigation

1. Reproduce the bug with the simplest possible input.
2. Read the actual error message / stack trace. Do NOT guess.
3. Trace the data flow backwards from the failure site to the origin.
4. Identify the earliest point where observed behavior diverges from expected.

Phase 2 -- Pattern Analysis

1. Search the codebase for similar patterns (same API, same data path).
2. Check recent changes (git log, git blame) near the failure site.
3. Look for related open issues or past fixes for the same component.
4. Note if the bug is deterministic or intermittent -- intermittent implies concurrency, timing, or external state.