---
name: performance-budget
description: "Applies “Performance is a budget, not a hope” as a repeatable product-quality gate. Use during frontend work when numbers written down, measured on the production build, enforced at the gate."
---

# Performance is a budget, not a hope

Apply this skill during **Frontend** work. It supports Next.js / React, Mobile, Any stack.

Numbers written down, measured on the production build, enforced at the gate.

## Instructions

Set performance budgets in writing before building: LCP under 2.5s, INP under 200ms, and a JavaScript budget per route. Measure only against the production build with CPU/network throttling — dev-mode numbers are fiction. Enforce image discipline: explicit dimensions, lazy loading below the fold, modern formats, preconnect to third-party hosts. Load fonts without layout shift (metric-compatible fallback or size-adjust). Justify every third-party script by name and business need; default is no. When a budget is exceeded, treat it as a failing test: the change doesn't merge until it fits or the budget is consciously re-negotiated in writing.

## Detect the problem

- 'Feels fast on my machine'
- A 400 kB hero image
- Analytics loading before content

## Hold the gate

Do not declare this phase complete until every item passes:

- [ ] Budgets exist in writing: LCP < 2.5s, INP < 200ms, per-route JS budget
- [ ] Measured against the production build on a throttled profile — never dev mode
- [ ] Images: sized, lazy below the fold, modern formats; fonts load without layout shift
- [ ] Every third-party script is justified line-by-line and loads after interactive
- [ ] The gate fails when a budget is exceeded — no 'we'll optimize later'

## Verify the result

Lighthouse the production build on a throttled mobile profile — budgets green or the merge waits.