Initial commit

skills/debugging-with-tools/resources/debugger-reference.md

@@ -0,0 +1,113 @@
+## Debugger Quick Reference
+
+### Automated Debugging (Claude CAN run these)
+
+#### lldb Batch Mode
+
+```bash
+# One-shot command to inspect variable at breakpoint
+lldb -o "breakpoint set --file main.rs --line 42" \
+     -o "run" \
+     -o "frame variable my_var" \
+     -o "quit" \
+     -- target/debug/myapp 2>&1
+
+# With script file for complex debugging
+cat > debug.lldb <<'EOF'
+breakpoint set --file main.rs --line 42
+run
+frame variable
+bt
+up
+frame variable
+quit
+EOF
+
+lldb -s debug.lldb target/debug/myapp 2>&1
+```
+
+#### strace (Linux - system call tracing)
+
+```bash
+# See which files program opens
+strace -e trace=open,openat cargo run 2>&1 | grep -v "ENOENT"
+
+# Find network activity
+strace -e trace=network cargo run 2>&1
+
+# All syscalls with time
+strace -tt cargo test some_test 2>&1
+```
+
+#### dtrace (macOS - dynamic tracing)
+
+```bash
+# Trace function calls
+sudo dtrace -n 'pid$target:myapp::entry { printf("%s", probefunc); }' -p <PID>
+```
+
+### Interactive Debugging (USER runs these, Claude guides)
+
+**These require interactive terminal - Claude provides commands, user runs them**
+
+### lldb (Rust, Swift, C++)
+
+```bash
+# Start debugging
+lldb target/debug/myapp
+
+# Set breakpoints
+(lldb) breakpoint set --file main.rs --line 42
+(lldb) breakpoint set --name my_function
+
+# Run
+(lldb) run
+(lldb) run arg1 arg2
+
+# When paused:
+(lldb) frame variable              # Show all locals
+(lldb) print my_var                # Print specific variable
+(lldb) bt                          # Backtrace (stack)
+(lldb) up / down                   # Navigate stack
+(lldb) continue                    # Resume
+(lldb) step / next                 # Step into / over
+(lldb) finish                      # Run until return
+```
+
+### Browser DevTools (JavaScript)
+
+```javascript
+// In code:
+debugger; // Execution pauses here
+
+// In DevTools:
+// - Sources tab → Add breakpoint by clicking line number
+// - When paused:
+//   - Scope panel: See all variables
+//   - Watch: Add expressions to watch
+//   - Call stack: Navigate callers
+//   - Step over (F10), Step into (F11)
+```
+
+### gdb (C, C++, Go)
+
+```bash
+# Start debugging
+gdb ./myapp
+
+# Set breakpoints
+(gdb) break main.c:42
+(gdb) break myfunction
+
+# Run
+(gdb) run
+
+# When paused:
+(gdb) print myvar
+(gdb) info locals
+(gdb) backtrace
+(gdb) up / down
+(gdb) continue
+(gdb) step / next
+```
+

skills/debugging-with-tools/resources/debugging-session-example.md

@@ -0,0 +1,73 @@
+## Example: Complete Debugging Session
+
+**Problem:** Test fails with "Symbol not found: _OBJC_CLASS_$_WKWebView"
+
+**Phase 1: Investigation**
+
+1. **Read error**: Symbol not found, linking issue
+2. **Internet research**:
+   ```
+   Dispatch hyperpowers:internet-researcher:
+   "Search for 'dyld Symbol not found _OBJC_CLASS_$_WKWebView'
+   Focus on: Xcode linking, framework configuration, iOS deployment"
+
+   Results: Need to link WebKit framework in Xcode project
+   ```
+
+3. **Debugger**: Not needed, linking happens before runtime
+
+4. **Codebase investigation**:
+   ```
+   Dispatch hyperpowers:codebase-investigator:
+   "Find other code using WKWebView - how is WebKit linked?"
+
+   Results: Main app target has WebKit in frameworks, test target doesn't
+   ```
+
+**Phase 2: Analysis**
+
+Root cause: Test target doesn't link WebKit framework
+Evidence: Main target works, test target fails, Stack Overflow confirms
+
+**Phase 3: Testing**
+
+Hypothesis: Adding WebKit to test target will fix it
+
+Minimal test:
+1. Add WebKit.framework to test target
+2. Clean build
+3. Run tests
+
+```
+Dispatch hyperpowers:test-runner: "Run: swift test"
+Result: ✓ All tests pass
+```
+
+**Phase 4: Implementation**
+
+1. Test already exists (the failing test)
+2. Fix: Framework linked
+3. Verification: Tests pass
+4. Update bd:
+   ```bash
+   bd close bd-123
+   ```
+
+**Time:** 15 minutes systematic vs. 2+ hours guessing
+
+## Remember
+
+- **Tools make debugging faster**, not slower
+- **hyperpowers:internet-researcher** can find solutions in seconds
+- **Automated debugging works** - lldb batch mode, strace, instrumentation
+- **hyperpowers:codebase-investigator** finds patterns you'd miss
+- **hyperpowers:test-runner agent** keeps context clean
+- **Evidence before fixes**, always
+
+**Prefer automated tools:**
+1. lldb batch mode - non-interactive variable inspection
+2. strace/dtrace - system call tracing
+3. Instrumentation - logging Claude can add
+4. Interactive debugger - only when automated tools insufficient
+
+95% faster to investigate systematically than to guess-and-check.