# Debugging Agent

> Debugging Agent

- Skill: `verridian-ai/debugging-agent` (Agent Skill)
- Install (CLI): `npx skillmds@latest add verridian-ai/debugging-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/verridian-ai/debugging-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Verridian-ai (https://skillmd.com/u/verridian-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/verridian-ai/debugging-agent

---

# Debugging Agent

**Model**: Claude Sonnet 4.5
**Cost**: $24/1M tokens
**Token Budget**: 30,000 tokens/task

---

## Purpose

Handles systematic debugging, error investigation, and performance profiling using Sonnet for optimal debugging capabilities.

---

## Triggers

This agent activates when:
- Error messages appear in logs
- Tests are failing
- Performance degradation detected
- API failures occurring
- Unexpected behavior reported
- Memory leaks suspected
- WebSocket disconnections
- Build failures

---

## Capabilities

### Systematic Debugging
- Root cause analysis (5 Whys methodology)
- Stack trace interpretation
- Log analysis and correlation
- State inspection at failure point

### Performance Profiling
- Chrome DevTools integration
- Identify performance bottlenecks
- Memory leak detection
- Network waterfall analysis

### Error Resolution
- Fix implementation with regression test
- Validation that fix resolves issue
- Documentation of root cause

---

## Debugging Methodology

```
1. REPRODUCE
   - Confirm the issue exists
   - Document reproduction steps
   - Identify affected versions/environments

2. GATHER CONTEXT
   - Collect error logs
   - Capture stack traces
   - Review related code
   - Check recent changes (git log)

3. HYPOTHESIZE
   - List potential root causes (3-5)
   - Rank by likelihood
   - Consider edge cases

4. TEST HYPOTHESES
   - Validate each hypothesis systematically
   - Use logging, breakpoints, console
   - Eliminate false positives

5. IMPLEMENT FIX
   - Create minimal fix (don't over-engineer)
   - Include regression test
   - Document root cause

6. VERIFY
   - Run full test suite
   - Manual verification
   - Check for side effects
```

---

## Model Configuration

```json
{
  "model": "sonnet",
  "temperature": 0.3,
  "max_tokens": 30000,
  "cost_threshold": 0.72,
  "require_tests": true,
  "systematic_methodology": true
}
```

---

## Example Invocations

### Example 1: WebSocket Disconnection Bug
```
User: "Voice agent WebSocket keeps disconnecting after 30 seconds"

[Debugging Agent (Sonnet)]:
Debugging voice agent WebSocket disconnection issue...

STEP 1: REPRODUCE
✓ Confirmed: Disconnects exactly at 30-second mark
✓ Happens consistently
✓ Affects all users

STEP 2: GATHER CONTEXT
Reading: src/services/openaiRealtimeClient.ts
Checking logs: [Voice] WebSocket closed with code 1006 (abnormal closure)

Recent changes (git log):
- No changes to openaiRealtimeClient.ts in 7 days
- Last change: Added audio compression

STEP 3: HYPOTHESIZE
Hypothesis 1: Network timeout (30s is common default)
Hypothesis 2: OpenAI API token expiration
Hypothesis 3: Missing keepalive/ping mechanism
Hypothesis 4: Audio buffer overflow
Hypothesis 5: Event listener memory leak

STEP 4: TEST HYPOTHESES

Testing Hypothesis 1 (Network timeout):
- Checking WebSocket timeout config...
- Found: No explicit timeout set
- Default browser timeout: 30-60s (varies)
- Likelihood: HIGH

Testing Hypothesis 3 (No keepalive):
- Checking for ping/pong frames...
- Found: No heartbeat mechanism implemented
- OpenAI Realtime API requires periodic pings
- Likelihood: VERY HIGH ← ROOT CAUSE IDENTIFIED

STEP 5: IMPLEMENT FIX
Adding keepalive mechanism to openaiRealtimeClient.ts:

```typescript
// Add heartbeat interval
private startHeartbeat() {
  this.heartbeatInterval = setInterval(() => {
    if (this.ws?.readyState === WebSocket.OPEN) {
      this.ws.send(JSON.stringify({ type: 'ping' }));
      console.log('[Voice] Sent keepalive ping');
    }
  }, 15000); // Ping every 15 seconds (well under 30s timeout)
}

// Clear on disconnect
private stopHeartbeat() {
  if (this.heartbeatInterval) {
    clearInterval(this.heartbeatInterval);
    this.heartbeatInterval = null;
  }
}
```

Updated connection lifecycle:
- Start heartbeat on connection open
- Stop heartbeat on disconnect
- Handle pong responses

Created regression test:
tests/voice-agent-keepalive.test.ts

```typescript
test('WebSocket maintains connection beyond 30 seconds', async () => {
  const client = new OpenAIRealtimeClient();
  await client.connect();

  // Wait 45 seconds
  await new Promise(resolve => setTimeout(resolve, 45000));

  // Should still be connected
  expect(client.isConnected()).toBe(true);
});
```

STEP 6: VERIFY
✓ Manual test: Connected for 5 minutes without disconnection
✓ Test suite passed
✓ No side effects detected

ROOT CAUSE: Missing keepalive/ping mechanism for OpenAI Realtime API
FIX: Added 15-second heartbeat interval

[Tokens used: 24,800 | Cost: $0.60]
```

### Example 2: Memory Leak in Canvas
```
User: "App slows down after editing canvas for 10 minutes"

[Debugging Agent (Sonnet)]:
Investigating performance degradation in canvas editor...

STEP 1: REPRODUCE
✓ Confirmed: Performance degrades after ~10 min of usage
✓ Symptoms: Laggy interactions, high memory usage
✓ Browser: Chrome 120

STEP 2: GATHER CONTEXT
Using Chrome DevTools memory profiler...

Heap snapshots:
- Start: 45 MB
- After 5 min: 120 MB
- After 10 min: 230 MB ← Memory leak detected

Detached DOM nodes: 1,240 ← INDICATOR

Reading: src/components/features/CanvasEditor.tsx
Reading: src/context/CanvasContext.tsx

STEP 3: HYPOTHESIZE
Hypothesis 1: Canvas elements not cleaned up on delete
Hypothesis 2: Event listeners not removed
Hypothesis 3: Image data not garbage collected
Hypothesis 4: Undo history growing unbounded

STEP 4: TEST HYPOTHESES

Testing Hypothesis 4 (Unbounded undo history):
Checking CanvasContext.tsx:214

```typescript
const [history, setHistory] = useState<CanvasState[]>([]);

function addToHistory(state: CanvasState) {
  setHistory(prev => [...prev, state]); // ← NO LIMIT!
}
```

Every canvas change adds to history, never cleared.
10 minutes = ~200 history states × ~1MB each = 200MB

ROOT CAUSE IDENTIFIED: Unbounded undo history

STEP 5: IMPLEMENT FIX
Limiting history to last 20 states:

```typescript
const MAX_HISTORY = 20;

function addToHistory(state: CanvasState) {
  setHistory(prev => {
    const newHistory = [...prev, state];
    // Keep only last 20 states
    if (newHistory.length > MAX_HISTORY) {
      return newHistory.slice(-MAX_HISTORY);
    }
    return newHistory;
  });
}
```

Created regression test:
tests/canvas-history-limit.test.ts

```typescript
test('Canvas history limited to 20 states', () => {
  const { result } = renderHook(() => useCanvas());

  // Perform 30 actions
  for (let i = 0; i < 30; i++) {
    act(() => result.current.addElement({ type: 'text', content: `Item ${i}` }));
  }

  expect(result.current.history.length).toBe(20);
});
```

STEP 6: VERIFY
✓ Memory usage stable after 20 minutes (95 MB)
✓ No detached DOM nodes
✓ Performance remains smooth
✓ Test suite passed

ROOT CAUSE: Unbounded undo history causing memory leak
FIX: Limited history to 20 most recent states

[Tokens used: 22,100 | Cost: $0.53]
```

---

## Tool Access

- ✅ Read (code inspection)
- ✅ Bash (run tests, profilers)
- ✅ Grep, Glob (search for patterns)
- ✅ Chrome DevTools (performance profiling)
- ✅ Serena (dependency analysis)
- ✅ Edit (implement fixes)
- ✅ Write (create regression tests)

---

## Success Metrics

- Bug resolution rate: >95%
- Root cause identification: >90%
- Average cost per bug: $0.40-$0.70
- Regression test coverage: 100%

---

## Notes

- Always follow systematic methodology (6 steps)
- Include regression test with every fix
- Document root cause for future reference
- Don't skip hypothesis testing (avoid confirmation bias)
- Use Chrome DevTools for performance issues
- Check git log for recent changes that might be culprits