ddtcorex/maestro-skills/magento2-performance-audit

Magento 2 Performance Audit

This skill performs a comprehensive audit of Magento 2 performance, infrastructure, and code-level patterns.

Govard-Native Audit Coverage

govard audit run executes PHPCS and PHPStan through Govard's pinned lint toolchain image — it covers coding-standard and static-analysis findings only. As of Govard v1.64.0 no performance audit check exists: govard audit run --checks performance fails with "audit check ... is not implemented". Govard v1.64.0 does add a native profiler check (--checks lint,profiler --url <url>) that machine-captures the stock profiler CSV for one URL — a quick complement to this skill's manual per-page audit, not a replacement: it ships no query log, no cross-page matrix, and no threshold analysis. The profiler requires a project target (not standalone), an absolute http(s) URL (the request carries Accept: text/html so stock Magento enables the CSV), and is guarded by a per-project diagnostics lease; the CSV lands as artifacts/profiler/profile.csv with its SHA in audit-result.json — open it as spreadsheet to read per-timer costs. Manual per-page captures (7 pages) cost ~2.5-3 min on their own (50k queries/page with call-stack, 16-26s each) — the full deep audit around them takes far longer, ~22m observed, see the observed floor above. Keep all 7, run with 300s timeout or background polling and trap restore, not by sampling fewer categories (that hides per-item N+1s). Keep running this checklist yourself and treat govard audit run --checks lint as the shared lint gate. Never present a lint-only pass as a performance verdict.

This is a checklist, not a menu. All 9 steps under Workflow (bottom of this file) run on every invocation — infra, indexer/cron, per-page-type capture, Slow Query Analysis, Cache Invalidation Efficiency, Client-Side AJAX Load, Core Web Vitals, code-level grep, report. Picking the steps that feel highest-signal for the effort and quietly dropping the rest (no admin creds, no Chrome DevTools MCP, "I already found a good bug") is the single most common failure mode of this skill — it produces a confident, well-formatted report that silently covers less than half the checklist. If a step genuinely can't run, say so in the report, under that step's own heading — Skipped: <reason> — never by omission. See the self-verification gate at the end of Workflow: the report is not done until it's been checked against the Audit Report Template line by line.

Distinguish a scoped ask from an unscoped one — this rule governs dropping steps quietly, not answering a narrower question. A general ask — "audit performance", "review this project before launch" — is unscoped: all 9 steps apply, none optional, exactly as above. When the user's own words name one specific category instead ("just check the MySQL query count", "audit N+1s only", "how many queries does the homepage run"), scope the work to that category and its reference file(s) — running the other 8 steps anyway would be answering a different question than the one asked. The obligation that carries over unchanged: state the scope explicitly (a "Scope" line/heading in the report) so the result is never mistaken for a full audit, and don't let scope creep run in either direction — no silently expanding a scoped ask back to all 9 steps, and no silently narrowing an unscoped one down to whichever step already found something.

Read the step's reference file before the first attempt at that step — not after improvising fails. Each "Full detail:" link owns its supported commands and environment traps: BusyBox grep inside govard sh, host/container DNS, Laminas renames, and DB privilege walls. If two attempts at a step fail, read that reference end to end before attempt 3. Never hand-edit app/etc/env.php to enable a diagnostic: it is deployment configuration, not an audit control surface; a syntax error takes every Magento CLI command down and cannot be reverted with git checkout when the file is gitignored.

Shared query-log captures require ownership. Before step 3, acquire the .performance-audit.lock session token described in references/database-query-profiling.md. A busy or foreign lock must fail-fast; do not remove a lock you do not own or treat its log as evidence.

Common ways this gets shortcut (don't)

Related Skills

REQUIRED BACKGROUND: Load magento2-dev-core first — code-level fixes for N+1 queries and heavy constructors follow the patterns it defines.

Part of the QA trio with magento2-linter and magento2-security-scan — together with magento2-dev-core, these form the "QA quartet" that magento2-code-review orchestrates at PR/module/theme/project scope. Findings use the shared M2-PERF-xxx codes cataloged in magento2-dev-core/references/severity-and-codes.md. Async/queue findings often point back to magento2-backend-dev.

Audit Categories

Nine categories, each with full commands/thresholds/edge-cases in its own reference file — read the relevant file when executing that step of the Workflow below, not all up front:

Quick / Deep — scope param (quick vs deep, quick 5–10m vs deep 20–30m)

This skill accepts a scope param: quick (PR check, cap 5–10m) or deep (release audit, 20–30m). The value quick.*deep on one line is intentional for tooling checks — keep the param name scope with those two literal values. Default to deep when the caller does not specify; callers that need a fast PR signal pass scope=quick.

Observed floor (reference large-project audit, verified 2026-09-21, deep scope): ~22m / 144 tool calls / ~332k tokens for the whole audit — setup, 7 captures, both passes, analysis, and report writing. Captures alone are only ~2.5–3 min of that (see references/per-page-type-audit.md); the rest is reading, cross-page analysis and the report. Use the total for the foreground/background + budget decision; it is an observation, not a commitment.

Report header (mandatory): every report starts with Scope: quick or Scope: deep on its first line (see references/report-template.md). Quick uses Scope: quick — 3 pages (1 home + 1 category + 1 product), Deep uses Scope: deep — 7 pages (1 home + 3 category small/medium/large + 3 product). Do not start a report without that line — it is how a reader tells PR vs release coverage at a glance.

Key verbatim mapping for quick 3 pages small/medium/large call-stack false threshold 1 quick files grid_per_page 48 cap 5–10m vs deep 7 pages double-pass call-stack true threshold 0 deep files 20–30m — keep these values in sync with references/per-page-type-audit.md and references/database-query-profiling.md.

Use the recipes, not hand-reading: do not open 50k lines of var/debug/db.log as a spreadsheet. Use the grep -c '## QUERY' / mysqldumpslow / pt-query-digest recipes in references/database-query-profiling.md. For lint use govard audit run --checks lint --format json on the host.

No stats tool exists for the query log. Do not hand-grep 16–50k lines; use the grep -c '## QUERY' / mysqldumpslow recipes below.