Performance Debugging Skill

Systematic procedures for profiling applications, identifying bottlenecks, and optimizing performance.

Overview

This skill provides workflows for performance analysis across Python, Node.js, and databases. Use it to profile code, generate flamegraphs, identify memory leaks, and apply algorithmic optimizations.

Principle: Measure first, optimize second. Never optimize without profiling.

Core Capabilities

1. CPU Profiling - cProfile (Python), Node.js profiler, flamegraph generation
2. Memory Analysis - Memory leaks, heap snapshots, allocation tracking
3. Database Optimization - Slow query analysis, EXPLAIN plans, index recommendations
4. Algorithmic Wins - O(n²) → O(n log n) refactors
5. Benchmarking - Before/after measurements, statistical significance

Quick Start

Common workflows:

• "Profile this Python function" → Use cProfile (see CPU Profiling section)
• "Find memory leak in Node.js" → Use heap snapshots (see Memory Profiling section)
• "Analyze slow query" → EXPLAIN ANALYZE <query> + indexing strategies
• "Generate flamegraph" → Use Node.js --prof + --prof-process

---

CPU Profiling

Python (cProfile)

Approach:

import cProfile
import pstats

profiler = cProfile.Profile()
profiler.enable()

# Your code here
slow_function()

profiler.disable()
stats = pstats.Stats(profiler)
stats.sort_stats('cumulative')
stats.print_stats(20)  # Top 20 functions

Node.js

# Generate profile
node --prof app.js

# Process profile output
node --prof-process isolate-*.log > profile.txt

Flamegraph Analysis

Read flamegraphs: Wide bars = lots of time, deep stacks = nested calls.

Reference: references/flamegraph-guide.md for interpretation patterns.

---

Memory Profiling

Python (memory_profiler)

Install: pip install memory_profiler

Usage:

from memory_profiler import profile

@profile
def my_function():
    # Your code here
    data = [i for i in range(1000000)]
    return data

Run: python -m memory_profiler script.py

Tracks memory usage line-by-line.

Node.js Heap Snapshots

node --inspect app.js
# Chrome DevTools → Memory → Take Heap Snapshot

Leak detection: Take snapshot, run workload, take another snapshot, compare.

Common Leak Patterns

• Unbounded caches (no eviction policy)
• Event listeners not removed
• Circular references (Python < 3.4)
• Global accumulator variables

Reference: references/memory-leak-patterns.md

---

Database Optimization

Slow Query Analysis

-- PostgreSQL
EXPLAIN ANALYZE SELECT * FROM users WHERE email = 'user@example.com';

-- MySQL
EXPLAIN FORMAT=JSON SELECT ...;

Key metrics:

• Seq Scan → needs index
• Rows → actual vs estimated (statistics outdated?)
• Buffers → cache hits vs disk reads

Index Recommendations

Approach: Look for:

• WHERE clauses without indexes
• JOIN columns without indexes
• ORDER BY/GROUP BY without covering indexes

Reference: references/indexing-strategies.md

---

Algorithmic Optimization

Common Patterns

Problem	Slow (O)	Fast (O)	Technique
Find duplicates	O(n²) nested loops	O(n) hash set	Use set()
Sorted search	O(n) linear scan	O(log n) binary search	bisect module
Frequent lookups	O(n) list search	O(1) dict lookup	Use dict
Range queries	O(n) full scan	O(log n) sorted + bisect	Sort first

Reference: references/optimization-patterns.md for detailed examples.

Profiling-Driven Refactor

1. Profile → identify hot path (95% time in one function)
2. Measure baseline → record current performance
3. Optimize → apply algorithmic improvement
4. Verify → re-profile, confirm improvement
5. Benchmark → statistical significance (t-test)

---

References

flamegraph-guide.md

How to read flamegraphs, common patterns (wide bars, recursive calls, GC pauses).

memory-leak-patterns.md

Common leak patterns by language (Python, Node.js, Go).

indexing-strategies.md

B-tree vs hash indexes, covering indexes, partial indexes, multi-column indexes.

optimization-patterns.md

Algorithmic optimizations with before/after code examples.

---

Best Practices

• Measure first: Never optimize without profiling data
• Focus on hot paths: 80/20 rule (80% time in 20% of code)
• Algorithmic wins > micro-optimizations: O(n²) → O(n log n) beats loop unrolling
• Statistical significance: Run benchmarks multiple times, use t-tests
• Verify assumptions: Profile after optimization to confirm improvement

---

Integration with Agents

performance-profiler agent - Performance analysis specialist that leverages this skill

How it works:

• Agent provides proactive performance monitoring and systematic analysis framework
• Agent coordinates multi-layer optimization (CPU, memory, database, network, frontend)
• Skill provides profiling scripts, workflows, and optimization patterns
• Single source of truth: All profiling procedures and scripts in skill, not duplicated in agent

Benefits:

• Token efficiency (agent 142 lines, skill 266 lines + scripts)
• Maintainability (update workflows/scripts once → agent benefits)
• Clear separation (agent = analysis framework, skill = implementation)

---

Integration with senior-swe Role

Role: Identify bottleneck, choose optimization strategy Skill: Execute profiling, generate reports, recommend changes

Workflow:

1. User: "This endpoint is slow"
2. senior-swe loads skill
3. Skill profiles code
4. Skill identifies bottleneck (e.g., O(n²) nested loop)
5. Role recommends algorithmic fix
6. Skill benchmarks before/after

---

Notes

Type: Guidance-Only (Type 6) - Provides profiling patterns, optimization strategies, and best practices without executable scripts

Portability: Self-contained .claude/skills/performance/ folder (shareable)

Pattern: External profiling tools (cProfile, Node.js profiler, EXPLAIN) used directly, skill provides workflows and interpretation guidance

---

See Also

• .claude/agents/roles/senior-swe.md
• docs/research/ace/core/alignment-constraints.md
• For related skills: introspection (cognitive debugging), quality-check (code quality gates)