performance-review

What this skill does

# Performance Review

Measure and evaluate your application's performance against Google's Core Web Vitals thresholds and industry benchmarks. This review catches performance issues that are invisible during development but impact real users — bundle bloat, layout shifts, slow interactions, unoptimized images, and render-blocking resources.

## When to use

Use `/performance-review` when:
- Before launching or after major feature additions
- Page load feels slow but you're not sure why
- Preparing for high-traffic events
- After adding new dependencies or third-party scripts
- SEO rankings depend on performance scores
- Users report slowness or abandonment

## Standards Referenced

- **Google Core Web Vitals** — LCP, INP, CLS (2024 thresholds)
- **Google Lighthouse** — Performance scoring methodology
- **HTTP Archive** — Web performance benchmarks (median, p75, p90)
- **Web.dev Performance Guidelines** — Best practices
- **RAIL Model** — Response, Animation, Idle, Load budgets

## Phase Overview

```
Phase 1: EDUCATE   → Performance impact on business and what we measure
Phase 2: SCOPE     → Identify key pages, performance budget, baseline
Phase 3: ANALYZE   → Browser-based performance measurement
Phase 4: REPORT    → Findings with metrics, scores, and comparisons
Phase 5: REMEDIATE → Fix guidance + YAML regression tests
```

---

## Phase 1: Educate

> **Why this matters:** A 1-second delay in page load reduces conversions by 7% (Akamai). Google uses Core Web Vitals as ranking signals since 2021. 53% of mobile visitors leave a page that takes >3 seconds to load (Google). Amazon found every 100ms of latency costs 1% of sales. Performance is a feature — and its absence is a bug.

This review measures real performance in a browser, not just static analysis. We capture actual load times, rendering behavior, and interaction responsiveness.

---

## Phase 2: Scope

### Gather context

1. **Auto-detect from codebase:**
   - Build system (Webpack, Vite, Next.js, etc.)
   - Bundle analysis setup (if any)
   - Image optimization pipeline (sharp, next/image, etc.)
   - Font loading strategy
   - Code splitting configuration
   - Service worker / caching strategy
   - CDN configuration

2. **Ask the user** (one at a time):
   - **Target URL**: Where is the app running? (production preferred for realistic measurements)
   - **Key pages**: Which pages matter most for performance? (recommend: landing page, main feature page, data-heavy page)
   - **Performance budget**: Any existing targets? (default: Core Web Vitals "Good" thresholds)
   - **Known concerns**: Any pages that feel slow? (optional)

3. **Define measurement plan:**
   - Pages to test (3-5 key pages)
   - Conditions: desktop and mobile simulated (Moto G4 / Slow 4G)
   - Metrics: Core Web Vitals + supplementary metrics
   - Baseline: first run establishes baseline for comparison

---

## Phase 3: Analyze

Open a browser session with `new_session` using `record_evidence: true`. For each page in scope, run all measurement categories.

### Category A: Core Web Vitals (CWV)

| Check ID | Metric | Good | Needs Improvement | Poor | Method |
|----------|--------|------|-------------------|------|--------|
| CWV-01 | **LCP** (Largest Contentful Paint) | ≤2.5s | 2.5-4.0s | >4.0s | `PerformanceObserver` for LCP entries |
| CWV-02 | **INP** (Interaction to Next Paint) | ≤200ms | 200-500ms | >500ms | Click key interactive elements, measure delay |
| CWV-03 | **CLS** (Cumulative Layout Shift) | ≤0.1 | 0.1-0.25 | >0.25 | `PerformanceObserver` for layout-shift entries |

**Browser validation:** Navigate to each page and capture metrics via JavaScript:

```javascript
// LCP
new PerformanceObserver((list) => {
  const entries = list.getEntries();
  const lcp = entries[entries.length - 1];
  console.log('LCP:', lcp.startTime);
}).observe({ type: 'largest-contentful-paint', buffered: true });

// CLS
let clsValue = 0;
new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (!entry.hadRecentInput) clsValue += entry.value;
  }
  console.log('CLS:', clsValue);
}).observe({ type: 'layout-shift', buffered: true });
```

### Category B: Page Load Performance (LOAD)

| Check ID | Check | Threshold | Method |
|----------|-------|-----------|--------|
| LOAD-01 | Time to First Byte (TTFB) | ≤800ms | `performance.timing.responseStart - navigationStart` |
| LOAD-02 | First Contentful Paint (FCP) | ≤1.8s | `performance.getEntriesByName('first-contentful-paint')` |
| LOAD-03 | DOM Content Loaded | ≤2.0s | `performance.timing.domContentLoadedEventEnd` |
| LOAD-04 | Total page weight | ≤3MB (mobile) / ≤5MB (desktop) | `performance.getEntriesByType('resource')` sum |
| LOAD-05 | Number of HTTP requests | ≤50 | Count resource entries |
| LOAD-06 | Time to Interactive (TTI) | ≤3.8s | Long task analysis |
| LOAD-07 | Total Blocking Time (TBT) | ≤200ms | Sum of long tasks (>50ms portions) |
| LOAD-08 | Speed Index | ≤3.4s | Visual progress analysis |

**Browser validation:** Use Performance API and `performance.getEntries()` to gather all metrics.

### Category C: Resource Optimization (RES)

| Check ID | Check | Standard | Method |
|----------|-------|----------|--------|
| RES-01 | Images use modern formats (WebP/AVIF) | Web.dev | Check image URLs and Content-Type |
| RES-02 | Images are appropriately sized (not oversized) | Web.dev | Compare display size vs natural size |
| RES-03 | Images use lazy loading (below-fold) | Web.dev | Check `loading="lazy"` on below-fold images |
| RES-04 | Images have explicit dimensions (width/height) | CLS prevention | Check for width/height attributes |
| RES-05 | CSS is not render-blocking (or is critical-inlined) | Web.dev | Check CSS loading strategy |
| RES-06 | JavaScript is deferred or async | Web.dev | Check script loading attributes |
| RES-07 | Fonts use font-display: swap or optional | Web.dev | Check @font-face declarations |
| RES-08 | Fonts are preloaded | Web.dev | Check for `<link rel="preload" as="font">` |
| RES-09 | Gzip/Brotli compression enabled | HTTP best practice | Check Content-Encoding headers |
| RES-10 | HTTP/2 or HTTP/3 in use | HTTP best practice | Check protocol via Performance API |
| RES-11 | Effective caching headers | HTTP best practice | Check Cache-Control on static assets |
| RES-12 | No unused CSS/JS loaded | Bundle efficiency | Check coverage via Page.startJSCoverage/startCSSCoverage |

**Browser validation:** Use JavaScript to inspect all loaded resources, their types, sizes, and loading attributes. Use `performance.getEntriesByType('resource')` for detailed resource metrics.

### Category D: Bundle Analysis (BUN)

| Check ID | Check | Threshold | Method |
|----------|-------|-----------|--------|
| BUN-01 | Main JS bundle size | ≤250KB gzipped | Check transfer size of main bundle |
| BUN-02 | Total JS size | ≤500KB gzipped | Sum all JS transfer sizes |
| BUN-03 | Total CSS size | ≤100KB gzipped | Sum all CSS transfer sizes |
| BUN-04 | Code splitting implemented | Best practice | Check for multiple JS chunks |
| BUN-05 | No duplicate dependencies | Bundle efficiency | Analyze chunk contents for duplicates |
| BUN-06 | Tree shaking effective | Bundle efficiency | Check for known large unused exports |
| BUN-07 | Source maps not exposed in production | Security/Performance | Check for .map files accessibility |
| BUN-08 | Third-party JS budget | ≤30% of total JS | Calculate third-party vs first-party ratio |

**Browser validation:** Use Performance API to measure transfer sizes. Check for source map URLs. Analyze script domain origins.

### Category E: Runtime Performance (RUN)

| Check ID | Check | Threshold | Method |
|----------|-------|-----------|--------|
| RUN-01 | No long tasks during interaction | >50ms = long task | Use `PerformanceObserver` for long tasks |
| RUN-02 | Scroll performance is smooth | 60fps | Scroll page, measure frame drops |
| RUN-03 | Animation performance | 60fps | Trigger animations, measure jank |
| RUN