Performance and caching
Speed comes from doing less work, then from doing it at the same time, and only last from remembering it. A cache added before measuring hides the slow part, adds stale data and a second source of truth. Read the file for the step:
| The step |
Read |
| Find where the time goes; validate benchmark work, errors, tuning, limits and repeated comparisons; cut round trips; parallelize (never ahead of auth checks or for CPU work); index; Vercel thresholds; deterministic counts and steering a perf push |
MEASURE.md |
| Push filtering, aggregation, ordering and limits into SQL; anti-joins, top N, window functions, sargable predicates, keyset pagination, index design and index regressions, full-text search |
QUERIES.md |
Add, fix or remove a cache at any layer; Vercel CDN headers, Vary, 404s and immutable; what cacheLife proves; module-level and browser storage caches; large lookup data: fetch granularity, cache tiers, Bloom filters, indexed shards |
CACHING.md |
| Browser loading, media, layout shifts, long lists, main-thread work, interaction traces and Lighthouse gates |
web-performance |
Read production metrics on Vercel with vercel metrics: setup checks and what each failure means, Observability Plus access and retention, the query catalog with documented metric names, the window, limit and rate rules, Core Web Vitals good limits, project vs team cost |
VERCEL-METRICS.md |
| Audit production cost and performance from metrics: candidate gates, bounded investigations, abstentions and evidence-backed recommendations |
TELEMETRY-AUDIT.md |
Apply only the routes and checks for the selected job. Read a linked skill's named file from its installed folder when available, or from the linked source. Report an unavailable required reference instead of inventing it. [skill-authoring, DISTRIBUTION.md#composing-skills]
The rules
- Measure before changing anything, with a breakdown (database, each external call, compute, serialization), on realistic data and load. Write the baseline down.
- Change one thing at a time and re-measure. A combined change can't tell you what helped, and one that didn't help should be reverted.
- Remove work before caching it: fewer queries, fewer round trips, smaller payloads, the right index. Then overlap independent waits.
- A cache is a copy with a staleness budget. Before adding one, write down how stale the data may be and who invalidates it. If nobody can answer, don't cache.
- The key is the complete set of inputs. Any input left out of the key (user, locale, permissions, version) serves someone else's result.
- Results are evidence for their workload. "15x faster" describes one endpoint, one data size, one machine. Report numbers with the conditions they were measured under, and don't promise them elsewhere.
- Keep concerns separate. Caching, timing and retries wrap the real function (a decorator or higher-order function); they don't get tangled into its body. The wrapping order decides what each one sees: timing outside the cache measures hits and misses, timing inside measures only misses.
Prove it
Before and after numbers for the same request, same data, same environment, each change measured separately. For a cache: the hit rate, the staleness after an update, and what happens on a cold start, a failing source and fifty concurrent misses for the same key.
1---2name: "performance-and-caching"3description: "Measures and improves server and query performance, caching and production cost: request breakdowns, bounded parallel waits, query plans and indexes, cache validity/invalidation, Vercel metrics and telemetry-led audits. Use when an endpoint or query is slow, an index is not used, a cache misbehaves, or production latency or cost needs investigation."4metadata:5 source: https://skillmd.com/skills/quegenx/performance-and-caching6---78# Performance and caching910Speed comes from doing less work, then from doing it at the same time, and only last from remembering it. A cache added before measuring hides the slow part, adds stale data and a second source of truth. Read the file for the step:1112| The step | Read |13|---|---|14| Find where the time goes; validate benchmark work, errors, tuning, limits and repeated comparisons; cut round trips; parallelize (never ahead of auth checks or for CPU work); index; Vercel thresholds; deterministic counts and steering a perf push | [MEASURE.md](MEASURE.md) |15| Push filtering, aggregation, ordering and limits into SQL; anti-joins, top N, window functions, sargable predicates, keyset pagination, index design and index regressions, full-text search | [QUERIES.md](QUERIES.md) |16| Add, fix or remove a cache at any layer; Vercel CDN headers, `Vary`, 404s and `immutable`; what `cacheLife` proves; module-level and browser storage caches; large lookup data: fetch granularity, cache tiers, Bloom filters, indexed shards | [CACHING.md](CACHING.md) |17| Browser loading, media, layout shifts, long lists, main-thread work, interaction traces and Lighthouse gates | [web-performance](https://github.com/Quegenx/agent-skills/blob/main/skills/web-ui/web-performance/SKILL.md) |18| Read production metrics on Vercel with `vercel metrics`: setup checks and what each failure means, Observability Plus access and retention, the query catalog with documented metric names, the window, limit and rate rules, Core Web Vitals good limits, project vs team cost | [VERCEL-METRICS.md](VERCEL-METRICS.md) |19| Audit production cost and performance from metrics: candidate gates, bounded investigations, abstentions and evidence-backed recommendations | [TELEMETRY-AUDIT.md](TELEMETRY-AUDIT.md) |2021Apply only the routes and checks for the selected job. Read a linked skill's named file from its installed folder when available, or from the linked source. Report an unavailable required reference instead of inventing it. [skill-authoring, DISTRIBUTION.md#composing-skills]2223## The rules24251. **Measure before changing anything,** with a breakdown (database, each external call, compute, serialization), on realistic data and load. Write the baseline down.262. **Change one thing at a time and re-measure.** A combined change can't tell you what helped, and one that didn't help should be reverted.273. **Remove work before caching it:** fewer queries, fewer round trips, smaller payloads, the right index. Then overlap independent waits.284. **A cache is a copy with a staleness budget.** Before adding one, write down how stale the data may be and who invalidates it. If nobody can answer, don't cache.295. **The key is the complete set of inputs.** Any input left out of the key (user, locale, permissions, version) serves someone else's result.306. **Results are evidence for their workload.** "15x faster" describes one endpoint, one data size, one machine. Report numbers with the conditions they were measured under, and don't promise them elsewhere.317. **Keep concerns separate.** Caching, timing and retries wrap the real function (a decorator or higher-order function); they don't get tangled into its body. The wrapping order decides what each one sees: timing outside the cache measures hits and misses, timing inside measures only misses.3233## Prove it3435Before and after numbers for the same request, same data, same environment, each change measured separately. For a cache: the hit rate, the staleness after an update, and what happens on a cold start, a failing source and fifty concurrent misses for the same key.
