Wp Performance

1---2name: wp-performance3description: "Use when investigating or improving WordPress performance (backend-only agent): profiling and measurement (WP-CLI profile/doctor, Server-Timing, Query Monitor via REST headers), database/query optimization, autoloaded options, object caching, cron, HTTP API calls, and safe verification."4compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Backend-only agent; prefers WP-CLI (doctor/profile) when available."5---6 7# WP Performance (backend-only)8 9## When to use10 11Use this skill when:12 13- a WordPress site/page/endpoint is slow (frontend TTFB, admin, REST, WP-Cron)14- you need a profiling plan and tooling recommendations (WP-CLI profile/doctor, Query Monitor, Xdebug/XHProf, APMs)15- you’re optimizing DB queries, autoloaded options, object caching, cron tasks, or remote HTTP calls16 17This skill assumes the agent cannot use a browser UI. Prefer WP-CLI, logs, and HTTP requests.18 19## Inputs required20 21- Environment and safety: dev/staging/prod, any restrictions (no writes, no plugin installs).22- How to target the install:23  - WP root `--path=<path>`24  - (multisite/site targeting) `--url=<url>`25- The performance symptom and scope:26  - which URL/REST route/admin screen27  - when it happens (always vs sporadic; logged-in vs logged-out)28 29## Procedure30 31### 0) Guardrails: measure first, avoid risky ops32 331. Confirm whether you may run write operations (plugin installs, config changes, cache flush).342. Pick a reproducible target (URL or REST route) and capture a baseline:35   - TTFB/time with `curl` if possible36   - WP-CLI profiling if available37 38Read:39- `references/measurement.md`40 41### 1) Generate a backend-only performance report (deterministic)42 43Run:44 45- `node skills/wp-performance/scripts/perf_inspect.mjs --path=<path> [--url=<url>]`46 47This detects:48 49- WP-CLI availability and core version50- whether `wp doctor` / `wp profile` are available51- autoloaded options size (if possible)52- object-cache drop-in presence53 54### 2) Fast wins: run diagnostics before deep profiling55 56If you have WP-CLI access, prefer:57 58- `wp doctor check`59 60It catches common production foot-guns (autoload bloat, SAVEQUERIES/WP_DEBUG, plugin counts, updates).61 62Read:63- `references/wp-cli-doctor.md`64 65### 3) Deep profiling (no browser required)66 67Preferred order:68 691. `wp profile stage` to see where time goes (bootstrap/main_query/template).702. `wp profile hook` (optionally with `--url=`) to find slow hooks/callbacks.713. `wp profile eval` for targeted code paths.72 73Read:74- `references/wp-cli-profile.md`75 76### 4) Query Monitor (backend-only usage)77 78Query Monitor is normally UI-driven, but it can be used headlessly via REST API response headers and `_envelope` responses:79 80- Authenticate (nonce or Application Password).81- Request REST responses and inspect headers (`x-qm-*`) and/or the `qm` property when using `?_envelope`.82 83Read:84- `references/query-monitor-headless.md`85 86### 5) Fix by category (choose the dominant bottleneck)87 88Use the profile output to pick *one* primary bottleneck category:89 90- **DB queries** → reduce query count, fix N+1 patterns, improve indexes, avoid expensive meta queries.91  - `references/database.md`92- **Autoloaded options** → identify the biggest autoloaded options and stop autoloading large blobs.93  - `references/autoload-options.md`94- **Object cache misses** → introduce caching or fix cache key/group usage; add persistent object cache where appropriate.95  - `references/object-cache.md`96- **Remote HTTP calls** → add timeouts, caching, batching; avoid calling remote APIs on every request.97  - `references/http-api.md`98- **Cron** → reduce due-now spikes, de-duplicate events, move heavy tasks out of request paths.99  - `references/cron.md`100 101### 6) Verify (repeat the same measurement)102 103- Re-run the same `wp profile` / `wp doctor` / REST request.104- Confirm the performance delta and that behavior is unchanged.105- If the fix is risky, ship behind a feature flag or staged rollout when possible.106 107## WordPress 6.9 performance improvements108 109Be aware of these 6.9 changes when profiling:110 111**On-demand CSS for classic themes:**112- Classic themes now get on-demand CSS loading (previously only block themes had this).113- Reduces CSS payload by 30-65% by only loading styles for blocks actually used on the page.114- If you're profiling a classic theme, this should already be helping.115 116**Block themes with no render-blocking resources:**117- Block themes that don't define custom stylesheets (like Twenty Twenty-Three/Four) can now load with zero render-blocking CSS.118- Styles come from global styles (theme.json) and separate block styles, all inlined.119- This significantly improves LCP (Largest Contentful Paint).120 121**Inline CSS limit increased:**122- The threshold for inlining small stylesheets has been raised, reducing render-blocking resources.123 124Reference: https://make.wordpress.org/core/2025/11/18/wordpress-6-9-frontend-performance-field-guide/125 126## Verification127 128- Baseline vs after numbers are captured (same environment, same URL/route).129- `wp doctor check` is clean (or improved) when applicable.130- No new PHP errors or warnings in logs.131- No cache flush is required for correctness (cache flush should be last resort).132 133## Failure modes / debugging134 135- “No change” after code changes:136  - you measured a different URL/site (`--url` mismatch), caches masked results, or opcode cache is stale137- Profiling data is noisy:138  - eliminate background tasks, test with warmed caches, run multiple samples139- `SAVEQUERIES`/Query Monitor causes overhead:140  - don’t run in production unless explicitly approved141 142## Escalation143 144- If this is production and you don’t have explicit approval, do not:145  - install plugins, enable `SAVEQUERIES`, run load tests, or flush caches during traffic146- If you need system-level profiling (APM, PHP profiler extensions), coordinate with ops/hosting.