@p.e.c/boaz-skills 1.3.0

package/skills/debug/checklists.md

@@ -0,0 +1,332 @@
+# Domain-Specific Debugging Checklists
+
+## A. Streaming/Buffer Issues
+
+### Symptoms
+- [ ] Video/audio stuttering or freezing
+- [ ] Increasing latency over time
+- [ ] Frame drops or artifacts
+- [ ] "Buffer underrun" or "overflow" errors
+
+### Investigation Checklist
+
+**1. Buffer Configuration**
+- [ ] Buffer size appropriate for data rate?
+- [ ] Ring buffer vs linear buffer — correct choice?
+- [ ] Buffer count sufficient for pipeline depth?
+
+**2. Flow Control**
+- [ ] Producer faster than consumer? (overflow)
+- [ ] Consumer faster than producer? (underrun)
+- [ ] Backpressure mechanism in place?
+- [ ] Flow control signals being respected?
+
+**3. Timing & Synchronization**
+- [ ] Clock drift between producer/consumer?
+- [ ] Timestamps monotonically increasing?
+- [ ] Frame timing consistent?
+- [ ] PTS/DTS handling correct?
+
+**4. Codec & Format**
+- [ ] Codec parameters match between encoder/decoder?
+- [ ] Resolution/framerate changes handled?
+- [ ] Keyframe interval appropriate?
+
+**5. Resource Contention**
+- [ ] CPU saturation during encoding/decoding?
+- [ ] Memory pressure causing GC pauses?
+- [ ] I/O blocking the pipeline?
+
+---
+
+## B. BLE/UART Communication
+
+### Symptoms
+- [ ] Connection drops
+- [ ] Data corruption
+- [ ] Timeout errors
+- [ ] Pairing failures
+
+### Investigation Checklist
+
+**1. Physical Layer (UART)**
+- [ ] Baud rate matching on both ends?
+- [ ] Correct parity, stop bits, flow control?
+- [ ] Cable/connection quality verified?
+- [ ] TX/RX not swapped?
+
+**2. Connection State (BLE)**
+- [ ] Device in discoverable/connectable mode?
+- [ ] Correct service UUID being used?
+- [ ] Connection interval appropriate?
+- [ ] MTU negotiated successfully?
+
+**3. Protocol Layer**
+- [ ] Message framing correct?
+- [ ] Checksums/CRCs matching?
+- [ ] Sequence numbers handled?
+- [ ] ACK/NAK protocol working?
+
+**4. Timing**
+- [ ] Timeouts set appropriately?
+- [ ] Retry logic in place?
+- [ ] Debouncing for connection state?
+
+**5. Power Management**
+- [ ] Device entering sleep during communication?
+- [ ] Wake-up latency accounted for?
+- [ ] Battery level affecting transmission power?
+
+---
+
+## C. AI Inference Bottlenecks
+
+### Symptoms
+- [ ] Slow inference time
+- [ ] High latency
+- [ ] Memory exhaustion
+- [ ] GPU underutilization
+
+### Investigation Checklist
+
+**1. Input Pipeline**
+- [ ] Preprocessing on CPU vs GPU?
+- [ ] Data loading blocking inference?
+- [ ] Input normalization correct?
+- [ ] Batch size optimal?
+
+**2. Model Loading**
+- [ ] Model loaded to correct device (CPU/GPU)?
+- [ ] Warmup run completed?
+- [ ] Model quantized if needed?
+- [ ] ONNX/TensorRT optimization applied?
+
+**3. Memory Management**
+- [ ] GPU memory sufficient?
+- [ ] Memory fragmentation?
+- [ ] Tensor allocation overhead?
+- [ ] Gradient tensors disabled for inference?
+
+**4. Batching**
+- [ ] Batch size vs latency tradeoff understood?
+- [ ] Dynamic batching configured?
+- [ ] Padding overhead minimized?
+
+**5. Output Processing**
+- [ ] Post-processing bottleneck?
+- [ ] NMS (Non-Max Suppression) optimized?
+- [ ] Output copying back to CPU?
+
+---
+
+## D. System Observability
+
+### Symptoms
+- [ ] "Unknown" failures
+- [ ] Intermittent issues hard to diagnose
+- [ ] Production differs from dev
+- [ ] No visibility into system state
+
+### Investigation Checklist
+
+**1. Metrics (USE Method)**
+- [ ] CPU utilization tracked?
+- [ ] Memory utilization tracked?
+- [ ] Disk I/O utilization tracked?
+- [ ] Network utilization tracked?
+- [ ] Saturation (queues) visible?
+- [ ] Error rates captured?
+
+**2. Logging**
+- [ ] Structured logging in place?
+- [ ] Log levels appropriate?
+- [ ] Request IDs/correlation IDs?
+- [ ] Sensitive data redacted?
+
+**3. Tracing**
+- [ ] Distributed tracing enabled?
+- [ ] Span context propagated?
+- [ ] Critical paths traced?
+- [ ] Trace sampling rate appropriate?
+
+**4. Alerting**
+- [ ] SLOs defined?
+- [ ] Alert thresholds tuned?
+- [ ] Alert fatigue addressed?
+- [ ] Runbooks linked to alerts?
+
+---
+
+## E. Network/API Issues
+
+### Symptoms
+- [ ] Connection refused/timeout
+- [ ] Slow responses
+- [ ] Intermittent failures
+- [ ] SSL/TLS errors
+
+### Investigation Checklist
+
+**1. Connectivity**
+- [ ] DNS resolution working?
+- [ ] Port accessible (firewall)?
+- [ ] Route to host exists?
+- [ ] VPN/proxy configured?
+
+**2. TLS/SSL**
+- [ ] Certificate valid and not expired?
+- [ ] Certificate chain complete?
+- [ ] TLS version compatible?
+- [ ] Cipher suites matching?
+
+**3. Request/Response**
+- [ ] Request format correct?
+- [ ] Headers set properly (auth, content-type)?
+- [ ] Response parsed correctly?
+- [ ] Error responses handled?
+
+**4. Timeouts**
+- [ ] Connection timeout set?
+- [ ] Read timeout set?
+- [ ] Total request timeout set?
+- [ ] Retry with backoff implemented?
+
+**5. Rate Limiting**
+- [ ] Rate limits known?
+- [ ] 429 responses handled?
+- [ ] Retry-After header respected?
+- [ ] Client-side throttling in place?
+
+---
+
+## F. Memory/Crash Issues
+
+### Symptoms
+- [ ] Segmentation fault
+- [ ] Out of memory (OOM)
+- [ ] Memory growing over time
+- [ ] Crash dumps
+
+### Investigation Checklist
+
+**1. Crash Analysis**
+- [ ] Stack trace available?
+- [ ] Core dump captured?
+- [ ] Signal type (SIGSEGV, SIGABRT)?
+- [ ] Faulting address meaningful?
+
+**2. Memory Leaks**
+- [ ] Memory profile taken over time?
+- [ ] Allocations tracked to source?
+- [ ] Circular references possible?
+- [ ] Cache eviction working?
+
+**3. Use-After-Free**
+- [ ] Object lifetime clear?
+- [ ] Dangling pointers possible?
+- [ ] Double-free possible?
+
+**4. Buffer Overflow**
+- [ ] Array bounds checked?
+- [ ] String operations safe?
+- [ ] Stack canaries enabled?
+
+**5. OOM**
+- [ ] Memory limits configured?
+- [ ] Swap enabled/disabled?
+- [ ] Large allocations identified?
+- [ ] Memory fragmentation?
+
+---
+
+## G. App Debugging
+
+### Symptoms
+- [ ] App crash
+- [ ] UI freeze
+- [ ] State inconsistency
+- [ ] Battery drain
+
+### Investigation Checklist
+
+**1. Lifecycle**
+- [ ] Correct lifecycle callbacks?
+- [ ] State saved on background?
+- [ ] Resources released on pause?
+- [ ] Orientation change handled?
+
+**2. Threading**
+- [ ] UI work on main thread only?
+- [ ] Long operations on background?
+- [ ] Thread safety for shared state?
+- [ ] Deadlock possible?
+
+**3. State Management**
+- [ ] State mutation predictable?
+- [ ] State persistence working?
+- [ ] State restoration working?
+- [ ] Race conditions in state updates?
+
+**4. Resource Leaks**
+- [ ] Listeners unregistered?
+- [ ] Subscriptions cancelled?
+- [ ] Bitmaps/buffers recycled?
+- [ ] Database connections closed?
+
+**5. Performance**
+- [ ] Layout passes optimized?
+- [ ] Overdraw minimized?
+- [ ] List recycling working?
+- [ ] Animation frame drops?
+
+---
+
+## H. Web Debugging (Playwright MCP)
+
+### Symptoms
+- [ ] Test flakiness
+- [ ] Element not found
+- [ ] Timeout errors
+- [ ] Visual differences
+
+### Investigation Checklist
+
+**1. Element Selection**
+- [ ] Selector stable (not index-based)?
+- [ ] Element in viewport?
+- [ ] Element not covered by overlay?
+- [ ] iFrame context correct?
+
+**2. Timing**
+- [ ] Wait for network idle?
+- [ ] Wait for animation complete?
+- [ ] Explicit wait for condition?
+- [ ] Timeout values appropriate?
+
+**3. State**
+- [ ] Cookies/storage set correctly?
+- [ ] Auth state valid?
+- [ ] Application state reset between tests?
+- [ ] Mock data consistent?
+
+**4. Network**
+- [ ] API mocking configured?
+- [ ] Network conditions simulated?
+- [ ] Request interception working?
+- [ ] Response validation?
+
+**5. Visual Regression**
+- [ ] Baseline images current?
+- [ ] Viewport size consistent?
+- [ ] Fonts loaded?
+- [ ] Animation disabled for screenshots?
+
+**6. Reproduction with Playwright MCP**
+```
+Steps to capture reproduction:
+1. Record failing scenario
+2. Capture DOM snapshot
+3. Capture network waterfall
+4. Capture console logs
+5. Generate reproduction script
+```

package/skills/debug/reference.md

@@ -0,0 +1,355 @@
+# Debugging Tool Reference
+
+Quick reference for common debugging tools and commands.
+
+---
+
+## System Observation
+
+### Process Information
+```bash
+# List processes
+ps aux | grep <name>
+pgrep -a <pattern>
+
+# Process tree
+pstree -p <pid>
+
+# Real-time process monitoring
+top -p <pid>
+htop
+
+# Process file descriptors
+lsof -p <pid>
+
+# Process memory map
+pmap <pid>
+cat /proc/<pid>/maps
+```
+
+### System Calls
+```bash
+# Trace system calls
+strace -f -p <pid>
+strace -e trace=network <command>
+strace -e trace=file <command>
+
+# macOS
+dtruss -p <pid>
+
+# Count system calls
+strace -c <command>
+```
+
+### Library Calls
+```bash
+# Trace library calls
+ltrace -p <pid>
+ltrace -e malloc+free <command>
+```
+
+### Kernel Messages
+```bash
+# Kernel ring buffer
+dmesg -T
+dmesg -T | tail -50
+dmesg -w  # follow mode
+
+# Journal (systemd)
+journalctl -f
+journalctl -u <service>
+journalctl --since "5 minutes ago"
+```
+
+---
+
+## Network Debugging
+
+### Connectivity
+```bash
+# DNS resolution
+dig <domain>
+nslookup <domain>
+host <domain>
+
+# Port check
+nc -zv <host> <port>
+telnet <host> <port>
+
+# Route tracing
+traceroute <host>
+mtr <host>
+
+# Active connections
+ss -tuln
+netstat -tuln
+lsof -i :<port>
+```
+
+### Packet Capture
+```bash
+# tcpdump basics
+tcpdump -i <interface>
+tcpdump -i any port <port>
+tcpdump -i any host <ip>
+tcpdump -w capture.pcap
+
+# HTTP traffic
+tcpdump -A -s0 port 80
+
+# With Wireshark
+wireshark -k -i <interface>
+tshark -i <interface> -Y "http"
+```
+
+### HTTP/API Testing
+```bash
+# curl basics
+curl -v <url>
+curl -X POST -H "Content-Type: application/json" -d '{}' <url>
+curl -w "@curl-format.txt" -o /dev/null -s <url>
+
+# curl timing template (curl-format.txt)
+# time_namelookup: %{time_namelookup}
+# time_connect: %{time_connect}
+# time_appconnect: %{time_appconnect}
+# time_pretransfer: %{time_pretransfer}
+# time_starttransfer: %{time_starttransfer}
+# time_total: %{time_total}
+
+# HTTPie (human-friendly)
+http GET <url>
+http POST <url> key=value
+```
+
+### SSL/TLS
+```bash
+# Certificate info
+openssl s_client -connect <host>:443
+openssl s_client -connect <host>:443 -servername <sni>
+
+# Certificate expiry
+echo | openssl s_client -connect <host>:443 2>/dev/null | openssl x509 -noout -dates
+```
+
+---
+
+## Performance Profiling
+
+### CPU Profiling
+```bash
+# perf (Linux)
+perf record -g <command>
+perf report
+perf top
+
+# CPU flame graph
+perf record -F 99 -g <command>
+perf script | stackcollapse-perf.pl | flamegraph.pl > flame.svg
+
+# time command
+time <command>
+/usr/bin/time -v <command>
+```
+
+### Memory Profiling
+```bash
+# Process memory
+free -h
+vmstat 1
+cat /proc/<pid>/status | grep -i mem
+
+# Heap analysis (Linux)
+valgrind --tool=massif <command>
+ms_print massif.out.*
+
+# Address sanitizer
+CFLAGS="-fsanitize=address" make
+ASAN_OPTIONS=detect_leaks=1 ./<program>
+```
+
+### I/O Profiling
+```bash
+# Disk I/O
+iostat -x 1
+iotop
+
+# File I/O per process
+strace -e trace=read,write -c <command>
+```
+
+---
+
+## Language-Specific
+
+### Python
+```bash
+# Profiling
+python -m cProfile -s cumtime script.py
+python -m py_spy top --pid <pid>
+python -m py_spy record -o profile.svg --pid <pid>
+
+# Memory
+python -m memory_profiler script.py
+tracemalloc  # in code
+
+# Debugging
+python -m pdb script.py
+python -c "import pdb; pdb.pm()"  # post-mortem
+```
+
+### Node.js
+```bash
+# Profiling
+node --prof app.js
+node --prof-process isolate*.log > processed.txt
+
+# Memory
+node --expose-gc --inspect app.js
+# Use Chrome DevTools Memory tab
+
+# Debugging
+node --inspect app.js
+node --inspect-brk app.js  # break on start
+```
+
+### Go
+```bash
+# Profiling
+go tool pprof http://localhost:6060/debug/pprof/profile
+go tool pprof http://localhost:6060/debug/pprof/heap
+
+# Race detection
+go run -race main.go
+go test -race ./...
+
+# Debugging
+dlv debug main.go
+dlv attach <pid>
+```
+
+### Rust
+```bash
+# Profiling
+cargo flamegraph
+perf record --call-graph dwarf cargo run
+
+# Memory
+cargo +nightly miri test  # undefined behavior
+
+# Debugging
+rust-gdb target/debug/<binary>
+rust-lldb target/debug/<binary>
+```
+
+---
+
+## Container/Docker
+
+```bash
+# Container logs
+docker logs -f <container>
+docker logs --tail 100 <container>
+
+# Container inspection
+docker inspect <container>
+docker stats <container>
+docker top <container>
+
+# Execute in container
+docker exec -it <container> sh
+docker exec -it <container> bash
+
+# Container health
+docker inspect --format='{{.State.Health}}' <container>
+```
+
+---
+
+## Kubernetes
+
+```bash
+# Pod logs
+kubectl logs -f <pod>
+kubectl logs -f <pod> -c <container>
+kubectl logs --previous <pod>
+
+# Pod inspection
+kubectl describe pod <pod>
+kubectl get pod <pod> -o yaml
+
+# Execute in pod
+kubectl exec -it <pod> -- sh
+kubectl exec -it <pod> -c <container> -- bash
+
+# Port forwarding
+kubectl port-forward <pod> <local>:<remote>
+
+# Events
+kubectl get events --sort-by='.lastTimestamp'
+```
+
+---
+
+## Git Debugging
+
+```bash
+# Find introducing commit
+git bisect start
+git bisect bad
+git bisect good <commit>
+# ... test each commit
+git bisect reset
+
+# Blame
+git blame <file>
+git log -p -S'<search string>'  # pickaxe
+
+# Diff analysis
+git diff HEAD~5..HEAD
+git diff --stat
+```
+
+---
+
+## Quick Recipes
+
+### Find What's Using Port
+```bash
+lsof -i :<port>
+ss -tulpn | grep :<port>
+netstat -tulpn | grep :<port>
+```
+
+### Find Large Files
+```bash
+du -sh * | sort -rh | head -20
+find . -type f -size +100M
+```
+
+### Watch File Changes
+```bash
+watch -n 1 'ls -la <file>'
+tail -f <file>
+```
+
+### Compare Outputs
+```bash
+diff <(command1) <(command2)
+vimdiff <(command1) <(command2)
+```
+
+### Measure Command Performance
+```bash
+hyperfine '<command1>' '<command2>'
+time bash -c 'for i in {1..100}; do <command>; done'
+```
+
+### Capture and Replay Traffic
+```bash
+# Record
+tcpdump -i any -w traffic.pcap
+
+# Replay
+tcpreplay -i <interface> traffic.pcap
+```