Magento 2 / Mage-OS Storefront Performance Audit

Audit procedure for Magento storefront performance. The output is always a severity-ranked markdown report (references/scoring.md) where every finding carries verbatim evidence and an exact fix — never a list of generic tips.

The cardinal rule: audit caching first. Until full-page cache works, every other number (TTFB, CWV, server load) is measuring the wrong thing. Most "Magento is slow" reports are FPC failures with a different hat on.

Pick the mode

Ask for the missing half only if the findings demand it (e.g. URL mode shows MISSes → request codebase access to find the killer); otherwise audit what you have and record the gap in the report's "Not audited" section.

URL mode

1. Collect 3–5 public URLs: homepage, a category page, a product page, a CMS page.

Never test cart/checkout/account pages for cache hits — they are uncacheable by design.

1. Run the header check (stdlib-only Python, two requests per URL so the second is warm):

   python scripts/check-headers.py https://store.example/ https://store.example/some-category \
       [--insecure]   # for local/dev self-signed certs

It measures TTFB cold/warm, payload size, compression, and parses X-Magento-Cache-Debug / Age / Varnish headers into pre-classified findings.

1. Interpret with references/fpc-audit.md — particularly the

header table and what a warm MISS means.

1. Frontend layer: read references/frontend-perf.md; run

Lighthouse/PageSpeed if available, otherwise estimate from the fetched HTML (script/CSS counts, LCP image preload, lazy-loading mistakes, third-party tags).

Codebase mode

1. FPC killers — scan layout XML for cacheable="false":

   python scripts/scan-layout.py /path/to/magento [--include-vendor] [--json]

Severity is pre-classified (default.xml → critical, catalog/CMS handles → critical, checkout/customer → info). For runtime killers the scan can't see (isScopePrivate, session starts in frontend blocks), follow references/fpc-audit.md.

1. env.php and stack — read app/etc/env.php against

references/server-config.md: cache/session backends and Redis DB separation, http_cache_hosts, deploy mode, OPcache. Never quote secrets (passwords, keys) from env.php into the report — name the key, not the value.

1. Indexers & cron — with a running install:

   bin/magento indexer:show-mode      # any 'realtime' on production = finding
   bin/magento indexer:status
   bin/magento cache:status           # full_page enabled?
   bin/magento deploy:mode:show

plus the cron_schedule checks in references/indexers-cron.md. Without a running install, audit crontab.xml groups and env.php cron_consumers_runner statically and note the rest as not-audited.

Write the report

Assemble findings using the template and scoring rubric in references/scoring.md. Non-negotiables:

• Every finding: verbatim evidence (header value, file:line, CLI output) + one concrete

fix + effort estimate.

• Rank by impact-per-effort. A critical FPC leak outranks ten image optimizations.
• Include the "Working as intended" section — name the scary-looking-but-correct things

(uncached checkout, cold-request slowness) so nobody "fixes" them.

• Include "Not audited" — what this mode couldn't see.
• For dev/staging targets, downgrade production-only findings (developer mode, exposed

debug headers) to info and say absolute timings need re-measuring on production.

Audit, don't fix

The deliverable is the report. Don't start editing layout XML or env.php unless the user asks for fixes — then switch to the magento-module skill conventions for any code changes, and re-run the relevant script afterwards to prove the finding is gone.

Pairing with live data

If the elgentos magento2-dev-mcp MCP server is connected, prefer it for reading merged layout/config when chasing an FPC killer — Magento merges XML across modules and themes, and the single-file view can mislead.