---
name: performance-budgeting
description: Measure + enforce performance budgets (Lighthouse, bundle, DB). Use before perf-sensitive releases.
---

# Skill: Performance Budgeting

## When to use

A page feels slow, a bundle grew, or before shipping a perf-sensitive feature.

## Budgets (from docs/performance-budgets.md)

| Metric                      | Budget      |
| --------------------------- | ----------- |
| Initial JS (Angular & Next) | ≤ 250 KB gz |
| LCP (3G)                    | ≤ 2.5s      |
| CLS                         | ≤ 0.1       |
| API p95                     | ≤ 300 ms    |
| DB query p95                | ≤ 50 ms     |

## Steps

1. Frontend: Lighthouse CI + `source-map-explorer` / bundle analyzer.
2. Backend: log p95 latency; capture EF/Prisma query plans (`EXPLAIN ANALYZE`).
3. Compare against budgets; rank breaches by user impact.

## Gotchas

- Measure on a throttled profile (3G + 4x CPU) — local dev numbers lie.
- The #1 backend offender is N+1 — use projection (`.Select()`) + `include` carefully.
- Lazy-load Angular routes; code-split Next.js; tree-shake icon imports.
- A 250 KB budget breaks fast — audit on every dependency add (`cost-agent` overlaps here).

## Validation

Every budget measured with numbers; breaches ranked; top-3 fixes proposed with expected gain.
