Performance Optimization

Performance Optimization

Overview

Systematically identify and resolve performance bottlenecks using measurement-driven methodology. This skill enforces a strict MEASURE-IDENTIFY-OPTIMIZE-VERIFY cycle, preventing premature optimization and speculation. Every optimization must produce measurable improvement or be reverted.

Announce at start: "I'm using the performance-optimization skill to diagnose and resolve bottlenecks."

Phase 1: MEASURE (Establish Baseline)

Goal: Capture real metrics before changing anything.

Actions

# Web: Lighthouse CI
npx lighthouse https://your-app.com --output=json --output-path=baseline.json

# API: load test with k6
k6 run --out json=baseline.json loadtest.js

# Database: slow query log
# PostgreSQL: SET log_min_duration_statement = 100;  -- log queries > 100ms

Record these numbers. They are the baseline against which improvement is measured.

STOP — Do NOT proceed to Phase 2 until:

• Baseline metrics are captured and saved
• Specific metric targets are defined (e.g., LCP < 2.5s)
• Measurement methodology is documented (so it can be repeated)

Phase 2: IDENTIFY (Find the Actual Bottleneck)

Goal: Use profiling tools to find WHERE time is spent. Do NOT guess.

Profiling Tool Selection Table

The bottleneck is almost never where you assume it is. Measure first.

STOP — Do NOT proceed to Phase 3 until:

• Profiling tool appropriate to the layer has been used
• Specific bottleneck is identified with data
• Bottleneck accounts for a significant portion of the problem

Phase 3: OPTIMIZE (Fix the Identified Bottleneck)

Goal: Apply the targeted fix. Change ONE thing at a time.

Optimization Decision Table

STOP — Do NOT proceed to Phase 4 until:

• Only ONE change has been made
• Change directly targets the identified bottleneck
• No unrelated changes were made alongside the optimization

Phase 4: VERIFY (Measure Again)

Goal: Re-run the exact same measurement from Phase 1.

Actions

1. Run the same profiling/measurement as Phase 1
2. Compare results:
   • Did the metric improve?
   • By how much?
   • Did any other metrics regress?
3. If improvement is not measurable, REVERT the change.

Optimization that cannot be measured is not optimization.

STOP — Verification complete when:

• Same measurement methodology used as Phase 1
• Improvement is quantified (e.g., "LCP reduced from 3.2s to 2.1s")
• No regressions in other metrics
• If no improvement: change reverted

Caching Strategy Decision Table

Cache-Control Headers

# Immutable assets (hashed filenames)
Cache-Control: public, max-age=31536000, immutable

# API responses (cacheable but must revalidate)
Cache-Control: public, max-age=0, must-revalidate
ETag: "abc123"

# Private user data
Cache-Control: private, no-store

# Stale-while-revalidate (fast response + background refresh)
Cache-Control: public, max-age=60, stale-while-revalidate=300

Bundle Optimization Techniques

Bundle Analysis Commands

# Webpack
npx webpack-bundle-analyzer stats.json

# Vite
npx vite-bundle-visualizer

# Next.js
ANALYZE=true next build

Database Query Tuning

Index Optimization

-- Find missing indexes (PostgreSQL)
SELECT schemaname, tablename, seq_scan, idx_scan
FROM pg_stat_user_tables
WHERE seq_scan > idx_scan
ORDER BY seq_scan DESC;

Index Rules

Query Plan Red Flags

Web Vitals Targets

Web Vitals Optimization Table

Load Testing

Test Types

Key Metrics

• Response time percentiles (p50, p95, p99) — not averages
• Error rate under load
• Throughput (requests per second)
• Resource utilization (CPU, memory, connections)

Anti-Patterns / Common Mistakes

Subagent Dispatch Opportunities

Follow the dispatching-parallel-agents skill protocol when dispatching.

Integration Points

Skill Type

FLEXIBLE — Adapt the depth of optimization to the project context. The MEASURE-IDENTIFY-OPTIMIZE-VERIFY cycle is mandatory for every optimization. Revert any change that does not produce measurable improvement.