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.

Performance Budgets

Reference document defining size and time budgets for web applications.

Size Budgets

JavaScript

CSS

Images

Fonts

Use font-display: swap or optional to prevent render blocking. Subset fonts to include only characters needed for the target language.

Time Budgets

API Response Times

Enforcing Budgets in CI

Lighthouse CI

# lighthouserc.js
module.exports = {
  ci: {
    assert: {
      assertions: {
        'categories:performance': ['error', { minScore: 0.9 }],
        'total-byte-weight': ['error', { maxNumericValue: 500000 }],
        'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
        'interactive': ['error', { maxNumericValue: 3000 }],
        'cumulative-layout-shift': ['error', { maxNumericValue: 0.1 }],
      },
    },
  },
};

# GitHub Actions
- name: Lighthouse CI
  run: |
    npm install -g @lhci/cli
    lhci autorun

bundlesize

// package.json
{
  "bundlesize": [
    { "path": "dist/main.*.js", "maxSize": "150 kB" },
    { "path": "dist/vendor.*.js", "maxSize": "100 kB" },
    { "path": "dist/*.css", "maxSize": "50 kB" }
  ]
}

# CI step
- name: Check bundle size
  run: npx bundlesize

size-limit

// package.json
{
  "size-limit": [
    { "path": "dist/index.js", "limit": "150 KB" },
    { "path": "dist/index.css", "limit": "50 KB" }
  ]
}

# CI step
- name: Check size limit
  run: npx size-limit

Webpack Performance Hints

// webpack.config.js
module.exports = {
  performance: {
    maxAssetSize: 250000,      // 250 KB per asset
    maxEntrypointSize: 300000,  // 300 KB per entry point
    hints: 'error',            // fail the build if exceeded
  },
};

Tools Summary

Monitoring in Production

CI budgets catch regressions before deploy. Production monitoring catches real-user issues.

Real User Monitoring (RUM)

// Report Web Vitals to analytics
import { onLCP, onINP, onCLS } from 'web-vitals';

onLCP(sendToAnalytics);
onINP(sendToAnalytics);
onCLS(sendToAnalytics);

Alerting Thresholds

Set alerts when p75 metrics exceed budgets:

Track trends over time. A slow drift upward is harder to catch than a sudden spike but equally damaging.