Deno Debugger Skill for Claude

Transform Claude into an interactive debugger for Deno/TypeScript applications.

This skill enables Claude to act as a debugging assistant that connects to Deno via the V8 Inspector Protocol, conducts systematic investigations, and generates comprehensive Markdown reports with evidence-based analysis.

🎯 What This Skill Does

Claude becomes your debugging partner that:

1. Connects to your Deno app via Chrome DevTools Protocol
2. Investigates using breakpoints, heap snapshots, and CPU profiling
3. Tracks investigation reasoning with breadcrumbs (for complex cases)
4. Analyzes data with native TypeScript (no external dependencies)
5. Reports findings in clear Markdown with specific recommendations

🚀 Quick Start

1. Install the Skill

# Copy to Claude's skills directory
cp -r deno-debugger/ ~/.claude/skills/

# That's it! No dependencies to install - uses Deno stdlib only

2. Launch Your Deno App with Inspector

# Start with --inspect (attaches on port 9229)
deno run --inspect --allow-net --allow-read your-app.ts

# Or use --inspect-brk to pause at start
deno run --inspect-brk --allow-net --allow-read your-app.ts

3. Ask Claude to Debug

You: "My Deno app is leaking memory when processing file uploads. Can you investigate?"

Claude: *connects via CDP, systematically investigates, generates REPORT.md*

📖 Usage Examples

Memory Leak Investigation

You: "Memory grows with each upload and never gets released"

Claude will:
1. Connect to your Deno process (port 9229)
2. Capture baseline heap snapshot
3. Trigger the leak (asks you or does it programmatically)
4. Capture comparison snapshot
5. Calculate growth rate and project OOM timeline
6. Examine source code for retention patterns
7. Generate REPORT.md with:
   - Root cause analysis
   - Code snippets showing the bug
   - Named anti-pattern (e.g., "retain-and-forget")
   - Production impact ("OOM after 22,543 uploads")
   - Specific fix with reasoning

Performance Bottleneck

You: "My API responses are slow, can you profile it?"

Claude will:
1. Start CPU profiling
2. Exercise the slow endpoint
3. Identify hot functions
4. Analyze algorithm complexity
5. Generate REPORT.md with:
   - Performance measurements (2.5s → 0.02s)
   - Hot path analysis
   - Algorithm complexity comparison (O(n²) → O(n log n))
   - Optimized implementation
   - Speedup projection (~100x)

Race Condition / Async Bug

You: "Sometimes my async operations complete in wrong order"

Claude will:
1. Set breakpoints at async boundaries
2. Trace execution flow
3. Check for missing awaits
4. Identify the race condition
5. Generate REPORT.md with fix and synchronization strategy

📊 Output Artifacts

Every investigation generates output in a directory of your choice (commonly investigation_output/):

• REPORT.md - Main investigation report (Markdown)
• baseline.heapsnapshot - Heap before (for memory issues)
• after.heapsnapshot - Heap after (for memory issues)
• profile.cpuprofile - CPU profile data (for performance issues)
• flamegraph.html - Interactive flamegraph visualization (optional)
• investigation.json - Breadcrumb timeline (if used)

Example Report Structure

# Investigation Report

**Date**: 2025-11-08
**Issue**: Memory leak in file upload handler

## Summary
Upload handler retains ArrayBuffer objects in global array without cleanup.

## Root Cause
The `handleUpload()` function pushes buffers to `leakedBuffers[]` but never
removes them. Each upload adds ~47 KB that persists for the app lifetime.

## Details
[Code snippet showing the bug with context]
[Anti-pattern explanation]
[Production impact: "OOM after 22,543 uploads (~225 hours)"]

## Location
- File: `app.ts`
- Line: 22
- Function: `handleUpload()`

## Fix
[Optimized code with clear reasoning]
[Why this solution works]

## Data
- Growth: 47 KB per upload
- Projected OOM: After ~22,543 uploads

🏗️ Architecture

deno-debug-skill/
├── deno-debugger/           # The actual skill (copy this to ~/.claude/skills/)
│   ├── SKILL.md            # Instructions Claude reads (workflow + patterns)
│   ├── README.md           # Installation guide (for users)
│   ├── deno.json           # Deno configuration with tasks
│   └── scripts/            # Pre-written debugging infrastructure (TypeScript)
│       ├── cdp_client.ts   # Chrome DevTools Protocol client
│       ├── heap_analyzer.ts  # Heap snapshot parsing (fast mode for 900MB heaps)
│       ├── cpu_profiler.ts   # CPU profiling with O(n²) detection & flamegraphs
│       ├── concurrent_helper.ts  # Race condition testing utilities
│       ├── breadcrumbs.ts  # Investigation tracking (optional)
│       ├── report_gen.ts   # Markdown report generation
│       ├── types.ts        # V8 and CDP type definitions
│       └── deps.ts         # Deno stdlib dependencies
│
├── examples/

...