ultimate-web-performance

name	ultimate-web-performance
description	Diagnose and improve end-user web performance with measured evidence. Use whenever the user's primary goal is a faster website or web app: performance audits, Core Web Vitals, Lighthouse/PageSpeed regressions, slow loads or navigations, interaction lag, animation jank, oversized bundles, render blocking, image/font delivery, caching, or a request to make performance-only changes. Supports a read-only AUDIT mode and an implementation EXECUTE mode. Do not trigger for ordinary React/Next.js coding where performance is only a general quality concern; use vercel-react-best-practices for that.
metadata	{"version":"1.0.0","status":"stable"}

Ultimate Web Performance

Treat performance work as an experiment, not a checklist. Establish a reproducible baseline, locate the limiting stage, change the smallest relevant cause, and measure again under comparable conditions.

This skill follows Semantic Versioning. Read CHANGELOG.md when comparing installations or updating the skill. Keep the directory and frontmatter name stable across versions so only one copy triggers.

Scope

Optimize the user-observed performance of browser-delivered experiences, including the server, database, CDN, and third-party work that directly contributes to that experience.

Stay within performance scope:

• Preserve behavior, accessibility, SEO, visual design, security, and data correctness.
• Report non-performance problems only when they block measurement or make a proposed performance change unsafe.
• Do not turn a performance task into a general refactor, dependency upgrade, design review, or quality audit.
• Do not optimize code merely because a pattern looks inefficient. Connect it to a measured bottleneck or an explicit performance budget.

For ordinary React or Next.js implementation, use vercel-react-best-practices if available. During a performance-only task, it may supply framework-specific implementation patterns, but measurements from this skill decide what to change and whether to keep it.

Choose the mode from the user's authorization

AUDIT — read-only

Use when the user asks to audit, inspect, analyze, diagnose, profile, review, or explain performance.

• Collect evidence and inspect source/history/configuration.
• Do not edit application files, install dependencies, change infrastructure, or publish results externally.
• End with ranked, testable experiments rather than claiming unimplemented improvements.

EXECUTE — make and verify changes

Use when the user asks to fix, improve, optimize, implement, or resolve a performance problem.

• Run the full measurement loop and edit only files needed for the selected bottleneck.
• Preserve unrelated dirty work.
• Make one attributable change at a time when practical.
• Keep a change only when correctness passes and measured results justify it.

If the request contains both audit and fix language, use EXECUTE. Audit first, then implement. If authorization is genuinely unclear and edits would be consequential, complete the read-only diagnosis and ask before editing.

Start with the performance contract

Infer what you safely can from the request and repository, then state the working contract briefly:

• Target journey: exact URL/route and the load, navigation, or interaction being optimized.
• User conditions: representative device, network, geography, authentication, data volume, and cache state.
• Success metric: field metric, lab metric, application timing, resource budget, or explicit user threshold.
• Correctness guard: behavior/tests that must remain unchanged.

Do not silently substitute “raise the Lighthouse score” for the user's actual symptom. A score is a diagnostic summary, not the product outcome.

Read only the references needed

• Read measurement-protocol.md before collecting or comparing measurements.
• Read diagnosis-playbook.md after the baseline, selecting only the section matching the symptom.
• For dependency-heavy Next.js/React applications, read nextjs-application-triage.md during orientation and load only the sections relevant to the measured route.
• When the bottleneck is React/Next.js code and vercel-react-best-practices is installed, read only its relevant rule files before editing.

Workflow

Track this compact ledger while working:

Experiment	Evidence and hypothesis	Change	Before	After	Variance	Correctness	Verdict

1. Orient

1. Inspect repository instructions, current status, stack, scripts, and existing performance tooling.
2. Identify pre-existing edits and do not absorb them into the performance change.
3. Look for existing budgets, RUM, traces, bundle reports, load tests, and prior failed experiments before creating new machinery.
4. Classify relevant dependencies by client, server, build, and development reachability. A package manifest is inventory, not evidence that code reaches a route or browser bundle.
5. Determine which available tools can measure the target. Prefer existing project tools; do not require one specific MCP or browser integration.

2. Measure a baseline

1. Prefer representative field data for prioritization when it exists.
2. Use controlled lab measurement to reproduce and explain the problem.
3. For load performance, capture the navigation and its network/CPU/rendering evidence.
4. For interaction performance, record the exact interaction; a load-only Lighthouse run cannot measure INP.
5. For server/data bottlenecks, trace the request path and measure the relevant spans, queries, or resource contention.
6. Repeat enough samples to expose normal run-to-run variation. Record raw runs, conditions, and an appropriate summary such as median plus range.

If a meaningful baseline cannot be obtained, do not invent one. Explain the limitation, use the strongest available proxy, and reduce confidence accordingly.

3. Locate the bottleneck

Build a causal chain from symptom to resource or code:

user symptom -> metric segment -> trace/request/query evidence -> owning code/config

Distinguish:

• Observation: directly measured fact.
• Attribution: evidence tying the observation to a cause.
• Hypothesis: plausible explanation not yet isolated.

Prioritize by expected user impact, confidence, reach, and implementation risk. Estimated tool savings are clues, not proof.

4. Run the highest-value experiment

In EXECUTE mode:

1. Choose the smallest change that tests the top hypothesis.
2. Predict which metric should move and why before editing.
3. Implement without changing visible behavior or broadening scope.
4. Run targeted correctness checks.
5. Remeasure with the same route, action, build mode, throttling, cache state, dataset, and sampling method.
6. Compare the delta with baseline variance and check secondary metrics for regressions.
7. Keep, revise, or revert the experiment based on evidence. Do not retain neutral complexity merely because it is already written.

Continue with the next bottleneck only while it remains within the user's requested scope and a safe, relevant experiment is available.

5. Guard the gain

When a change is kept:

• Add or adjust the narrowest practical performance budget, regression test, or monitoring hook if the repository already supports it or the user requested it.
• Avoid introducing a large monitoring system as incidental work.
• Record commands, conditions, raw results location, and known limitations so another agent can reproduce the comparison.

Tool strategy

Choose by question, not habit:

Question	Useful evidence
Real users are slow?	RUM, CrUX/PageSpeed field data, APM, production percentiles
Cold page load is slow?	DevTools performance trace, network waterfall, Lighthouse, server timing
A click or input lags?	Reproduced interaction trace, event timing, React profiler where relevant
Navigation/data feels slow?	Request waterfall, server spans, query timings, cache behavior
Bundle or dependency regressed?	Production build stats, chunk graph, coverage, dependency diff
Rendering or scrolling janks?	Frames, long tasks, style/layout/paint events, layer evidence

Fallbacks are valid. If browser automation is unavailable, use project scripts, Lighthouse CLI, build analyzers, existing telemetry, or give exact reproduction steps. Do not stop solely because a preferred tool is missing.

Decision rules

• Field data defines the population problem; lab data explains a reproducible case. Do not present one as the other.
• Compare production builds with production builds. Development-mode timings are diagnostic only.
• Control cache state deliberately; neither cold nor warm is universally correct.
• Measure the user journey, not just the easiest URL.
• Treat a single run as anecdotal.
• Avoid fixed universal bundle or latency budgets. Use product constraints, current field data, and repository budgets.
• Verify current metric definitions and thresholds from primary sources before quoting them; performance tooling changes.
• Never claim an improvement from code inspection alone.

Output contract

AUDIT output

1. Verdict — whether a confirmed performance problem exists and where.
2. Measurement context — route/journey, environment, build, cache/throttling, samples, and limitations.
3. Baseline — raw/summary metrics with field versus lab clearly labeled.
4. Bottlenecks — ranked table with evidence, attribution confidence, user impact, and owning code/config.
5. Experiments — minimal proposed changes, predicted metric, validation command, and risk.
6. Already healthy — major areas checked that do not justify work.

EXECUTE output

1. Outcome — the measured user-facing result.
2. Changes kept — files and causal rationale.
3. Before/after — comparable samples, variance, secondary metrics, and conditions.
4. Correctness — tests and behavior checks.
5. Discarded experiments — what was reverted and why.
6. Remaining limits — only material performance work still supported by evidence.

Use precise language: “median LCP changed from X to Y across N runs under Z” rather than “the page is much faster.”