/optimizing-performance

name: optimizing-performance
description: Guides performance optimization, profiling techniques, and bottleneck identification. Use when improving application speed, reducing resource usage, or diagnosing performance issues.
license: MIT
compatibility: opencode
metadata:
  category: quality
  audience: developers

Optimizing Performance

Strategies for identifying, analyzing, and resolving performance bottlenecks.

When to Use This Skill

• Application is running slowly
• High resource consumption (CPU, memory)
• Database queries are slow
• API response times are high
• Need to scale for more users
• Preparing for load testing

---

Performance Optimization Philosophy

The Golden Rules

1. **Measure first** - Never optimize without data 2. **Optimize the right thing** - Find the actual bottleneck 3. **Keep it simple** - Complexity often hurts performance 4. **Test after** - Verify the optimization worked 5. **Document trade-offs** - Performance often costs readability

The 80/20 Rule

80% of performance problems come from 20% of the code.

Focus on:
├── Hot paths (frequently executed code)
├── I/O operations (database, network, disk)
├── Memory allocation patterns
└── Algorithm complexity

---

Profiling Techniques

Types of Profiling

| Type | What It Measures | Tools | |------|------------------|-------| | CPU Profiling | Time spent in functions | pprof, py-spy, Chrome DevTools | | Memory Profiling | Allocation patterns, leaks | Valgrind, memory_profiler, Chrome | | I/O Profiling | Disk/network operations | strace, perf, Wireshark | | Database Profiling | Query performance | EXPLAIN, slow query log, APM |

Profiling Workflow

1. Establish baseline
   └─ Measure current performance with realistic load

2. Identify hotspots
   └─ Profile to find where time/resources are spent

3. Form hypothesis
   └─ Why is this slow? What would make it faster?

4. Implement fix
   └─ Make ONE change at a time

5. Measure again
   └─ Did it help? By how much?

6. Repeat
   └─ Until performance goals are met

Common Profiling Commands

# Node.js
node --prof app.js
node --prof-process isolate-*.log > profile.txt

# Python
python -m cProfile -s cumtime app.py
py-spy record -o profile.svg -- python app.py

# Go
go test -cpuprofile cpu.prof -memprofile mem.prof -bench .
go tool pprof cpu.prof

# Database (PostgreSQL)
EXPLAIN ANALYZE SELECT * FROM users WHERE email = 'test@example.com';

---

Common Bottleneck Patterns

N+1 Query Problem

BAD (N+1 queries):
  SELECT * FROM posts;             -- 1 query
  SELECT * FROM users WHERE id=1;  -- N queries
  SELECT * FROM users WHERE id=2;
  ...

GOOD (2 queries):
  SELECT * FROM posts;
  SELECT * FROM users WHERE id IN (1, 2, 3, ...);

**Detection**: High query count relative to data returned **Fix**: Eager loading, batch fetching, JOINs

Unbounded Operations

BAD:
  SELECT * FROM logs;  -- Returns millions of rows

GOOD:
  SELECT * FROM logs
  WHERE created_at > NOW() - INTERVAL '1 day'
  LIMIT 100;

**Detection**: Memory spikes, timeouts **Fix**: Pagination, limits, streaming

Synchronous Blocking

BAD (blocking):
  result1 = fetch_api_1()  -- Wait 200ms
  result2 = fetch_api_2()  -- Wait 200ms
  return combine(result1, result2)  -- Total: 400ms

GOOD (parallel):
  [result1, result2] = await Promise.all([
    fetch_api_1(),
    fetch_api_2()
  ])  -- Total: ~200ms

**Detection**: Sequential I/O in traces **Fix**: Parallel execution, async/await

Excessive Allocation

BAD (allocates in loop):
  for item in large_list:
      result = []  # Allocates each iteration
      result.append(transform(item))

GOOD (pre-allocate):
  result = []
  for item in large_list:
      result.append(transform(item))

BEST (generator):
  def transform_all(items):
      for item in items:
          yield transform(item)

**Detection**: GC pressure, memory profiling **Fix**: Object pooling, pre-allocation, generators

---

Optimization Techniques

Database Optimization

| Technique | When to Use | Impact | |-----------|-------------|--------| | **Indexing** | Slow WHERE/JOIN queries | High | | **Query optimization** | Complex queries | High | | **Connection pooling** | Many short connections | Medium | | **Read replicas** | Read-heavy workloads | High | | **Caching** | Repeated queries | Very High | | **Denormalization** | Complex JOINs | Medium |

Index Guidelines

-- Create index for frequently queried columns
CREATE INDEX idx_users_email ON users(email);

-- Composite index for multiple column queries
CREATE INDEX idx_orders_user_date ON orders(user_id, created_at);

-- Check if index is used
EXPLAIN ANALYZE SELECT * FROM users WHERE email = 'test@example.com';

Caching Strategies

| Strategy | Use Case | Invalidation | |----------|----------|--------------| | **Cache-aside** | General purpose | Manual or TTL | | **Write-through** | Strong consistency | On write | | **Write-behind** | Write-heavy | Async batched | | **Read-through** | Read-heavy | On miss |

Cache-aside pattern:
1. Check cache
2. If miss, query database
3. Store in cache
4. Return result

Memory Optimization

| Technique | When to Use | |-----------|-------------| | Object pooling | Frequent allocation of same type | | Lazy loading | Large objects not always needed | | Streaming | Processing large datasets | | Weak references | Cache that can be evicted | | Data structure choice | Right structure for access pattern |

---

Frontend Performance

Core Web Vitals

| Metric | Target | What It Measures | |--------|--------|------------------| | LCP (Largest Contentful Paint) | < 2.5s | Load performance | | INP (Interaction to Next Paint) | < 200ms | Interactivity | | CLS (Cumulative Layout Shift) | < 0.1 | Visual stability |

Frontend Optimization Checklist

Loading Performance:
  ☐ Code splitting (lazy load routes/components)
  ☐ Tree shaking (remove un