performance-budget

# 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