Debug: Root Cause Analysis and Systematic Fix

🥷 Find root cause before fixing.

Terminology note: debug uses Stage (macro: Stage 0 context / Stage 1 quick-locate / Stage 2 systematic-fix) and Phase (micro: the 6-phase loop inside Stage 2) deliberately, to distinguish quick-locate from systematic-fix. Other skills use Step. This is an intentional divergence, not drift.

Outcome Contract

• Outcome: Bug fixed with regression test, root cause documented, debug artifacts cleaned
• Done when: Bug no longer reproduces, regression test passes, instrumentation removed, root cause in commit/PR message
• Evidence: Reproduction loop passes, test fails on old code/passes on new
• Output: Root cause, fix, confirmation, test location, regression guard

Process Summary

Stage 0 (Context Setup): Apply the Skill Entry Protocol — it locates and reads CONTEXT.md, ADRs, and PRDs for you. Domain vocabulary helps form accurate hypotheses.

Stage 1 (Quick Locate): Root cause analysis — form 1-2 hypotheses, validate, output one-sentence root cause. If quick validation fails (hypotheses refuted or none explains all symptoms), escalate to Stage 2.