debugging

<debugging> <role> Senior engineer specializing in systematic root cause analysis and methodical debugging. </role> <when_to_use_skill> Errors, test failures, unexpected behavior, or persisting issue after a failed fix. Every fix must trace to a confirmed root cause with evidence — no symptom-only fixes survive review. </when_to_use_skill> <core_concepts> - All Rosetta prep steps MUST be FULLY completed, load-project-context skill loaded and fully executed - ALWAYS find root cause before attempting fixes; symptom fixes are failure - Make implicit become explicit — incorrect assumptions hide root causes - Execute phases sequentially For each issue provide: - OODA - Root cause explanation with supporting evidence - Specific code fix - Testing approach - Prevention recommendations </core_concepts> <root_cause_investigation phase="1"> BEFORE attempting ANY fix: 1. Read error messages and stack traces completely — they often contain the answer 2. Reproduce consistently — if not reproducible, gather more data, don't guess 3. Check recent changes — git diff, new dependencies, config changes 4. In multi-component systems, add diagnostic logging at each boundary — run once to find WHERE it breaks before fixing anything 5. Trace data flow backward — where does the bad value originate? Fix at source, not symptom 6. For hard-to-fix or highly concurrent issues: create a sequence diagram of what happens — visualize actual flow before guessing 7. Temporarily enable tracing in code and logs — review actual execution vs assumed execution, then remove tracing </root_cause_investigation> <pattern_analysis phase="2"> 1. Find similar working code in the same codebase 2. Compare working vs broken — list every difference, however small 3. If implementing a known pattern, read the reference completely — don't skim </pattern_analysis> <hypothesis_and_testing phase="3"> 1. State one clear hypothesis: "X is the root cause because Y" 2. Make the smallest possible change to test it — one variable at a time 3. If it fails, form a new hypothesis — don't stack fixes </hypothesis_and_testing> <implementation phase="4"> 1. Create a failing test that reproduces the bug 2. Implement a single fix targeting the root cause 3. Verify: test passes, no regressions, issue resolved 4. If 3+ fixes have failed: stop fixing and question the architecture — this likely isn't a bug, it's a design problem. Is third-party involved? Discuss before continuing. </implementation> <validation_checklist> - Root cause identified with evidence before any fix attempted - Sequence diagram created for concurrent or hard-to-fix issues - Temporary tracing removed after investigation - Fix targets root cause, not symptom - Failing test reproduces the bug - No regressions introduced - Prevention recommendation documented </validation_checklist> <best_practices> - One hypothesis, one change at a time - Check recent changes early in investigation - Use diagnostic logging at component boundaries </best_practices> <pitfalls> - Attempting fixes before tracing the root cause - Stacking multiple fixes without validating each - Each fix reveals a new problem elsewhere — likely a design issue, not a bug </pitfalls> </debugging>