## Curation Note This skill emerged from viral discussions about Claude Code V2's agentic capabilities. The core pattern: instead of asking a human to provide reproduction steps and narrow down the issue, the AI agent takes responsibility for the entire debugging lifecycle. The test-first verification approach prevents the common failure mode where a "fix" introduces new bugs or doesn't actually solve the problem. Particularly effective for complex, multi-file bugs that require understanding system interactions. ## Debugging Lifecycle ### Phase 1: Bug Intake and Context Gathering ``` 1. Parse bug report for: - Error messages or stack traces - Steps to reproduce - Expected vs. actual behavior - Environment details - Screenshots or logs 2. Gather codebase context: - Identify relevant files and modules - Review recent changes to affected areas - Check for related issues or previous fixes - Understand the component architecture ``` ### Phase 2: Reproduction Before attempting any fix, confirm the bug exists: ```python def reproduce_bug(bug_report): """ 1. Set up environment matching report 2. Execute steps to reproduce 3. Verify error matches description 4. Document exact reproduction steps """ test_case = create_reproduction_test(bug_report) result = run_test(test_case) if result.passed: return request_additional_info(bug_report) return document_reproduction(test_case, result) ``` **Key principle:** Write a failing test that demonstrates the bug before attempting any fix. ### Phase 3: Root Cause Analysis Systematic investigation approach: ``` 1. TRACE: Follow execution path from trigger to error - Add logging at key decision points - Track data transformations - Note where behavior diverges from expected 2. ISOLATE: Narrow down the problematic component - Binary search through code path - Test with minimal inputs - Remove variables until bug disappears 3. HYPOTHESIZE: Form theories about the cause - List possible explanations - Rank by likelihood - Design tests to confirm/refute each 4. VERIFY: Prove the root cause - Create targeted test that fails due to identified cause - Confirm fix addresses root cause, not symptom ``` ### Phase 4: Fix Implementation ```python def implement_fix(root_cause, reproduction_test): """ 1. Design fix that addresses root cause 2. Consider edge cases and side effects 3. Implement with minimal changes 4. Document reasoning for approach """ assert reproduction_test.fails() apply_fix(root_cause) assert reproduction_test.passes() all_tests = run_all_tests() assert all_tests.no_regressions() ``` ### Phase 5: Verification Multi-level verification ensures fix quality: ``` Level 1: Reproduction test passes Level 2: Related unit tests pass Level 3: Integration tests pass Level 4: Full test suite passes Level 5: Manual verification (if applicable) ``` ## Debugging Patterns ### Stack Trace Analysis ```python def analyze_stack_trace(trace: str): """Extract actionable information from stack trace.""" frames = parse_frames(trace) app_frames = [f for f in frames if not is_library(f)] root_frame = app_frames[-1] if app_frames else frames[-1] return { "file": root_frame.file, "line": root_frame.line, "function": root_frame.function, "error_type": extract_error_type(trace), "error_message": extract_error_message(trace), "context": get_code_context(root_frame) } ``` ### Binary Search Debugging For bugs that appear between two known states: ```bash git bisect start git bisect bad HEAD git bisect good v1.0.0 git bisect run npm test ``` ### State Inspection ```python def inspect_state_at_failure(): """Capture complete state when bug occurs.""" add_debug_logging( input_values=True, intermediate_state=True, function_calls=True, external_responses=True ) trace = run_with_trace(reproduction_steps) return find_divergence(trace, expected_behavior) ``` ## Autonomous Workflow ### Self-Directed Investigation ``` 1. Start with bug report 2. Attempt reproduction (max 3 attempts) - If fails: request more info, pause - If succeeds: continue 3. Investigate root cause (max 30 minutes) - Document findings progressively - If stuck: summarize findings, request help 4. Implement fix 5. Verify fix (all test levels) - If regressions: revert, try alternative 6. Document solution 7. Create PR with fix and tests ``` ### Decision Points When to escalate to human: ``` - Cannot reproduce after 3 attempts - Root cause unclear after 30 minutes investigation - Fix requires architectural changes - Multiple valid fix approaches exist - Fix impacts security-critical code - Change exceeds defined scope ``` ### Progress Reporting ```markdown ## Bug Investigation: #1234 ### Status: Investigating Root Cause **Reproduction:** ✅ Confirmed - Test added: `tests/test_auth.py::test_session_expiry_bug` **Findings:** 1. Session tokens not invalidated on password change 2. Old sessions remain valid until natural expiry 3. Issue introduced in commit abc123 **Next Steps:** 1. Add invalidation logic to password change handler 2. Verify with reproduction test 3. Check for similar patterns elsewhere **ETA:** 15 minutes for fix + verification ``` ## Best Practices 1. **Always reproduce first** - Never fix what you can't demonstrate 2. **Write test before fix** - Proves fix actually works 3. **Minimal changes** - Reduce risk of side effects 4. **Document reasoning** - Future you will thank present you 5. **Check for patterns** - One bug often reveals others 6. **Verify thoroughly** - Run full test suite, not just new test 7. **Know when to stop** - Escalate rather than thrash 8. **Leave breadcrumbs** - Log what you tried, even failed approaches ## Related Resources - [Debugging: The 9 Indispensable Rules](https://debuggingrules.com/) - [How to Debug](https://jvns.ca/blog/2019/06/23/a-few-debugging-resources/) - [Test-Driven Bug Fixing](https://www.industriallogic.com/blog/test-driven-bug-fixing/)