Performance Budget Skill

Produce a complete, actionable performance budget document for a web service or application. A performance budget is not a wishlist — it is a set of measurable, enforced constraints that define what "acceptable performance" means and who is responsible when those constraints are violated.

A good performance budget answers: what are the targets, how are they measured, what triggers an investigation, and what happens when a budget is breached.

Required Inputs

Ask for these if not already provided:

Service name and type — web app, API service, mobile app, or combination
Key user journeys — the 3–5 most important flows users take (e.g. "search → product page → checkout")
Current baseline metrics — P50/P95/P99 latency, LCP, CLS, INP if available (state "no baseline" if not collected yet)
Tech stack — frontend framework, backend language/framework, CDN, database
Deployment environment — cloud provider, region(s), edge/CDN configuration
Cost constraints — any budget or infrastructure limits that affect headroom

Output Format

Performance Budget: [Service Name]

Service: [Name] | Team: [Team name] Last updated: [Date] | Owner: [Name / role] Environment: [Production / Staging baseline] | Review cadence: [Quarterly / per-sprint]

Overview

[2–3 sentences describing the service, its user-facing performance requirements, and why performance is a priority. Reference the business impact of latency — e.g. conversion rate, user retention, SLA obligations.]

Performance philosophy: [e.g. "Performance is a feature. Every engineer is responsible for keeping the service within budget. Regressions must be caught in CI before they reach production."]

Key User Journeys

Define the critical paths that the performance budget is designed to protect.

Journey ID	Journey name	Entry point	Exit point	Criticality
UJ-1	[e.g. New user sign-up]	[Landing page]	[Dashboard]	Critical
UJ-2	[e.g. Core workflow task]	[e.g. /app/tasks]	[e.g. Task complete]	High
UJ-3	[e.g. Search and select]	[e.g. /search]	[e.g. Detail page]	High
UJ-4	[e.g. API data fetch]	[e.g. GET /api/items]	[e.g. 200 response]	Medium

Frontend Performance Budget

Complete this section for web and mobile applications. Skip for API-only services.

Core Web Vitals Targets

Targets apply to the 75th percentile of real user sessions (field data), measured on a mid-range Android device on a 4G connection unless otherwise stated.

Metric	Description	Good	Needs Improvement	Poor	Our Target	Current baseline
LCP	Largest Contentful Paint — perceived load speed	≤2.5s	2.5–4.0s	>4.0s	[≤X.Xs]	[Xs / not measured]
INP	Interaction to Next Paint — responsiveness	≤200ms	200–500ms	>500ms	[≤Xms]	[Xms / not measured]
CLS	Cumulative Layout Shift — visual stability	≤0.1	0.1–0.25	>0.25	[≤0.X]	[X.XX / not measured]
FCP	First Contentful Paint	≤1.8s	1.8–3.0s	>3.0s	[≤X.Xs]	[Xs / not measured]
TTFB	Time to First Byte	≤800ms	800ms–1.8s	>1.8s	[≤Xms]	[Xms / not measured]

Page Weight Budget

Asset type	Max size (compressed)	Current	Status
Total page weight	[e.g. 500KB]	[XKB / unknown]	[Within / Over / Unknown]
JavaScript (initial load)	[e.g. 200KB]	[XKB / unknown]	[Within / Over / Unknown]
CSS	[e.g. 50KB]	[XKB / unknown]	[Within / Over / Unknown]
Images (above fold)	[e.g. 150KB]	[XKB / unknown]	[Within / Over / Unknown]
Web fonts	[e.g. 50KB]	[XKB / unknown]	[Within / Over / Unknown]
Third-party scripts	[e.g. 100KB]	[XKB / unknown]	[Within / Over / Unknown]

Per-Journey Frontend Targets

Journey	LCP	INP	CLS	FCP	TTFB
UJ-1: [Journey name]	[≤Xs]	[≤Xms]	[≤0.X]	[≤Xs]	[≤Xms]
UJ-2: [Journey name]	[≤Xs]	[≤Xms]	[≤0.X]	[≤Xs]	[≤Xms]
UJ-3: [Journey name]	[≤Xs]	[≤Xms]	[≤0.X]	[≤Xs]	[≤Xms]

Backend Performance Budget

API Latency SLOs

Targets measured at the service boundary (not including client-side network latency).

Endpoint / operation	Method	P50	P95	P99	Max (hard limit)	Error rate
[e.g. /api/auth/login]	POST	[≤Xms]	[≤Xms]	[≤Xms]	[≤Xms]	[<X%]
[e.g. /api/items]	GET	[≤Xms]	[≤Xms]	[≤Xms]	[≤Xms]	[<X%]
[e.g. /api/items/:id]	GET	[≤Xms]	[≤Xms]	[≤Xms]	[≤Xms]	[<X%]
[e.g. /api/items]	POST	[≤Xms]	[≤Xms]	[≤Xms]	[≤Xms]	[<X%]
[e.g. Background job: sync]	—	[≤Xs]	[≤Xs]	[≤Xs]	[≤Xs]	[<X%]

Overall service SLOs:

SLO	Target	Measurement window
Availability	[99.X%]	30-day rolling
P95 latency (all endpoints)	[≤Xms]	30-day rolling
Error rate (5xx)	[<X%]	30-day rolling
Throughput (sustained)	[≥X req/s]	Peak hour

Database Query Budget

Query / operation	P50	P95	Max	Notes
[e.g. User lookup by ID]	[≤Xms]	[≤Xms]	[≤Xms]	Index on `user_id`
[e.g. List items for user]	[≤Xms]	[≤Xms]	[≤Xms]	Paginated, max 100 rows
[e.g. Full-text search]	[≤Xms]	[≤Xms]	[≤Xms]	Elasticsearch / pg_trgm

Measurement Methodology

Real User Monitoring (RUM)

Tool: [e.g. Google CrUX, SpeedCurve, Datadog RUM, Sentry Performance, custom] Data source: [Field data from real users / Lab data from synthetic tests / Both] Sample rate: [X% of sessions] How to access: [Dashboard URL or tool access instructions]

What is measured:

Core Web Vitals (LCP, INP, CLS) per page and journey
Custom performance marks for business-critical interactions
Resource timing for key assets
Long tasks (>50ms on main thread)

Synthetic Monitoring

Tool: [e.g. Lighthouse CI, WebPageTest, k6, Artillery, Playwright with performance assertions] Frequency: [Every X minutes / on every deploy / nightly] Test location(s): [e.g. eu-west-1, us-east-1] Device profile: [Desktop 10Mbps / Mobile 4G Moto G4 / both]

Synthetic test suite location: [Link to test files]

Backend Observability

APM tool: [e.g. Datadog, Grafana + Prometheus, New Relic, AWS X-Ray] Metrics collected:

Request rate, error rate, duration (RED metrics) per endpoint
Database query duration and connection pool utilisation
Cache hit/miss rates
Background job queue depth and processing latency

Dashboard: [Link to primary performance dashboard]

CI/CD Performance Enforcement

Performance budgets are enforced at two gates:

Gate 1 — Build-time Bundle Analysis

Tool: [e.g. bundlesize, size-limit, webpack-bundle-analyzer with CI assertion] Config file: [[.bundlesizerc / .size-limit.js / etc.]] Trigger: Every PR targeting main Blocking: Yes — PR cannot merge if bundle size budget is exceeded

// Example .size-limit.js
[
  {
    "path": "dist/js/*.js",
    "limit": "200 KB"
  },
  {
    "path": "dist/css/*.css",
    "limit": "50 KB"
  }
]

Gate 2 — Synthetic Performance Tests in CI

Tool: [e.g. Lighthouse CI, k6, Artillery] Trigger: On deploy to staging Blocking: Yes — production deploy is blocked if thresholds fail Thresholds checked:

LCP ≤ [Xs]
CLS ≤ [0.X]
P95 API latency ≤ [Xms]
Error rate < [X%]

CI config location: [[.github/workflows/perf.yml / ci/performance.yaml]]

How to run locally:

# Run Lighthouse CI against local build
[command — e.g. lhci autorun --config=lighthouserc.js]

# Run load test locally
[command — e.g. k6 run load-tests/api-smoke.js]

Budget Breach Response Process

A budget breach is when a measured metric exceeds its target for [X consecutive measurements / X minutes sustained / a single deploy].

Breach Severity Levels

Severity	Condition	Response time	Who acts
P1 — Critical	>2× budget threshold in production	Immediate	On-call engineer + team lead
P2 — High	>1.5× budget threshold in production	Within 4 hours	On-call engineer
P3 — Medium	Threshold exceeded in production	Within 1 sprint	PR author + team
P4 — Low	Threshold exceeded in staging only	Before merge	PR author

Breach Investigation Checklist

When a breach is detected, work through this checklist in order:

1. Identify the regression commit

# Compare performance across recent deploys
[command — e.g. datadog metrics query, lighthouse-ci compare, git bisect]

2. Classify the breach

Is this a code change? (new feature, refactor, dependency bump)
Is this an infrastructure change? (new instance type, config change)
Is this an external factor? (CDN issue, DNS, upstream dependency)
Is this a measurement anomaly? (test environment issue, sample size)

3. Immediate actions

If P1/P2 in production and a code cause is confirmed: roll back or disable the feature flag
If cause is unknown: do not roll back immediately — gather more data first
Notify [#performance / #incidents Slack channel] with: metric name, current value, budget target, suspected cause

4. Resolution

Fix the root cause — do not just adjust the budget threshold
Budget thresholds should only change after a team discussion and explicit approval from [tech lead / EM]
Document the breach in the [performance log / incident record]

Budget change policy: Budget thresholds may only be relaxed if: (a) the feature delivering the regression has measurable business value that outweighs the performance cost, and (b) the change is reviewed and approved by [tech lead].

Performance Review Cadence

Trigger	Action
Every sprint	Review P95/P99 latency trends; flag any creeping degradation
Every quarter	Full performance budget review — update baselines, adjust targets, audit tooling
After major feature launch	Re-measure all Core Web Vitals and API SLOs; update baselines
After infrastructure change	Re-run full synthetic test suite; confirm no regression
After dependency upgrade	Run bundle size diff; confirm no unexpected size increase

Next scheduled review: [Date] Review owner: [Name / role]

Quality Checks

Every budget threshold is a specific number — not a range or "TBD"
Both frontend (if applicable) and backend targets are defined — not just one or the other
Measurement tooling is named with a link to the dashboard or config file
CI enforcement is configured for at least one gate (build-time or deploy-time)
Budget breach response process names specific Slack channels and owners
Budget thresholds are anchored to baseline measurements or a justified target — not pulled from thin air
Per-journey targets are defined for critical user journeys, not just global averages

Anti-Patterns

Do not set budget thresholds without measuring a current baseline first — targets must be anchored to reality
Do not define global averages only — critical user journeys need individual budgets as they may diverge significantly
Do not omit CI enforcement — a performance budget that is not enforced in the build pipeline will not be respected
Do not leave the breach response process without named owners and escalation channels
Do not set budgets that apply only to one environment — production and staging targets should be documented separately if they differ

Performance Budget