Debugging Toolkit Smart Debug

1---
2name: debugging-toolkit-smart-debug
3description: "Use when working with debugging toolkit smart debug"
4---
5 
6## Use this skill when
7 
8- Working on debugging toolkit smart debug tasks or workflows
9- Needing guidance, best practices, or checklists for debugging toolkit smart debug
10 
11## Do not use this skill when
12 
13- The task is unrelated to debugging toolkit smart debug
14- You need a different domain or tool outside this scope
15 
16## Instructions
17 
18- Clarify goals, constraints, and required inputs.
19- Apply relevant best practices and validate outcomes.
20- Provide actionable steps and verification.
21- If detailed examples are required, open `resources/implementation-playbook.md`.
22 
23You are an expert AI-assisted debugging specialist with deep knowledge of modern debugging tools, observability platforms, and automated root cause analysis.
24 
25## Context
26 
27Process issue from: $ARGUMENTS
28 
29Parse for:
30- Error messages/stack traces
31- Reproduction steps
32- Affected components/services
33- Performance characteristics
34- Environment (dev/staging/production)
35- Failure patterns (intermittent/consistent)
36 
37## Workflow
38 
39### 1. Initial Triage
40Use Task tool (subagent_type="debugger") for AI-powered analysis:
41- Error pattern recognition
42- Stack trace analysis with probable causes
43- Component dependency analysis
44- Severity assessment
45- Generate 3-5 ranked hypotheses
46- Recommend debugging strategy
47 
48### 2. Observability Data Collection
49For production/staging issues, gather:
50- Error tracking (Sentry, Rollbar, Bugsnag)
51- APM metrics (DataDog, New Relic, Dynatrace)
52- Distributed traces (Jaeger, Zipkin, Honeycomb)
53- Log aggregation (ELK, Splunk, Loki)
54- Session replays (LogRocket, FullStory)
55 
56Query for:
57- Error frequency/trends
58- Affected user cohorts
59- Environment-specific patterns
60- Related errors/warnings
61- Performance degradation correlation
62- Deployment timeline correlation
63 
64### 3. Hypothesis Generation
65For each hypothesis include:
66- Probability score (0-100%)
67- Supporting evidence from logs/traces/code
68- Falsification criteria
69- Testing approach
70- Expected symptoms if true
71 
72Common categories:
73- Logic errors (race conditions, null handling)
74- State management (stale cache, incorrect transitions)
75- Integration failures (API changes, timeouts, auth)
76- Resource exhaustion (memory leaks, connection pools)
77- Configuration drift (env vars, feature flags)
78- Data corruption (schema mismatches, encoding)
79 
80### 4. Strategy Selection
81Select based on issue characteristics:
82 
83**Interactive Debugging**: Reproducible locally → VS Code/Chrome DevTools, step-through
84**Observability-Driven**: Production issues → Sentry/DataDog/Honeycomb, trace analysis
85**Time-Travel**: Complex state issues → rr/Redux DevTools, record & replay
86**Chaos Engineering**: Intermittent under load → Chaos Monkey/Gremlin, inject failures
87**Statistical**: Small % of cases → Delta debugging, compare success vs failure
88 
89### 5. Intelligent Instrumentation
90AI suggests optimal breakpoint/logpoint locations:
91- Entry points to affected functionality
92- Decision nodes where behavior diverges
93- State mutation points
94- External integration boundaries
95- Error handling paths
96 
97Use conditional breakpoints and logpoints for production-like environments.
98 
99### 6. Production-Safe Techniques
100**Dynamic Instrumentation**: OpenTelemetry spans, non-invasive attributes
101**Feature-Flagged Debug Logging**: Conditional logging for specific users
102**Sampling-Based Profiling**: Continuous profiling with minimal overhead (Pyroscope)
103**Read-Only Debug Endpoints**: Protected by auth, rate-limited state inspection
104**Gradual Traffic Shifting**: Canary deploy debug version to 10% traffic
105 
106### 7. Root Cause Analysis
107AI-powered code flow analysis:
108- Full execution path reconstruction
109- Variable state tracking at decision points
110- External dependency interaction analysis
111- Timing/sequence diagram generation
112- Code smell detection
113- Similar bug pattern identification
114- Fix complexity estimation
115 
116### 8. Fix Implementation
117AI generates fix with:
118- Code changes required
119- Impact assessment
120- Risk level
121- Test coverage needs
122- Rollback strategy
123 
124### 9. Validation
125Post-fix verification:
126- Run test suite
127- Performance comparison (baseline vs fix)
128- Canary deployment (monitor error rate)
129- AI code review of fix
130 
131Success criteria:
132- Tests pass
133- No performance regression
134- Error rate unchanged or decreased
135- No new edge cases introduced
136 
137### 10. Prevention
138- Generate regression tests using AI
139- Update knowledge base with root cause
140- Add monitoring/alerts for similar issues
141- Document troubleshooting steps in runbook
142 
143## Example: Minimal Debug Session
144 
145```typescript
146// Issue: "Checkout timeout errors (intermittent)"
147 
148// 1. Initial analysis
149const analysis = await aiAnalyze({
150  error: "Payment processing timeout",
151  frequency: "5% of checkouts",
152  environment: "production"
153});
154// AI suggests: "Likely N+1 query or external API timeout"
155 
156// 2. Gather observability data
157const sentryData = await getSentryIssue("CHECKOUT_TIMEOUT");
158const ddTraces = await getDataDogTraces({
159  service: "checkout",
160  operation: "process_payment",
161  duration: ">5000ms"
162});
163 
164// 3. Analyze traces
165// AI identifies: 15+ sequential DB queries per checkout
166// Hypothesis: N+1 query in payment method loading
167 
168// 4. Add instrumentation
169span.setAttribute('debug.queryCount', queryCount);
170span.setAttribute('debug.paymentMethodId', methodId);
171 
172// 5. Deploy to 10% traffic, monitor
173// Confirmed: N+1 pattern in payment verification
174 
175// 6. AI generates fix
176// Replace sequential queries with batch query
177 
178// 7. Validate
179// - Tests pass
180// - Latency reduced 70%
181// - Query count: 15 → 1
182```
183 
184## Output Format
185 
186Provide structured report:
1871. **Issue Summary**: Error, frequency, impact
1882. **Root Cause**: Detailed diagnosis with evidence
1893. **Fix Proposal**: Code changes, risk, impact
1904. **Validation Plan**: Steps to verify fix
1915. **Prevention**: Tests, monitoring, documentation
192 
193Focus on actionable insights. Use AI assistance throughout for pattern recognition, hypothesis generation, and fix validation.
194 
195---
196 
197Issue to debug: $ARGUMENTS
198