Magento 2 Performance Audit

Static analysis (N+1 patterns, missing cache identities, expensive plugins) with optional runtime inspection (indexer status, cache hit rates, slow queries, queue backlog).

Core Rules

• Static-first. Default pass uses only the source tree — no runtime, no Magento CLI required.
• Runtime is opt-in. Phase 3 runs only when the user passes --runtime.
• Severity by impact at scale. A 50ms ViewModel call in a non-storefront context is Low; an N+1 query in checkout is High.
• Concrete recommendation. Every finding includes the specific replacement pattern, not "improve performance."
• JSON + SARIF. Same shape as review.

Workflow

Phase 0 — Context Resolution

Invoke context. Note presence of Magento CLI, Redis CLI, DB CLI, Blackfire.

Phase 1 — Scope

• Single module → static analysis only by default; runtime opt-in.
• Multiple modules → static analysis across all; runtime opt-in.
• Site-wide → static across all custom modules + runtime checks.

Phase 2 — Static Pass

Per references/perf-checklist.md:

Run via ${CLAUDE_SKILL_DIR}/scripts/static-perf.sh <module-path>.

Phase 3 — Runtime Pass (Opt-in)

Only if user authorizes AND Magento CLI is present:

${CLAUDE_SKILL_DIR}/scripts/runtime-checks.sh automates the tool-based probes (indexer, cache, queue, Redis) and emits them as findings. The DB (pending cron), slow-log, and Varnish rows are run manually when their source is reachable — the script does not emit a slow_query finding, so do not claim a slow-query result unless the slow log was actually read.

Phase 4 — Optional: Blackfire / Tideways Integration

If BLACKFIRE_* env vars or ~/.blackfire.ini present:

• Prompt user to run a profiled URL.
• Parse Blackfire profile JSON.
• Surface top 10 hotspots with file:line references.

Phase 5 — Report

Two automation artifacts and one LLM deliverable:

1. JSON + SARIF (automated). ${CLAUDE_SKILL_DIR}/scripts/build-findings.sh aggregates static-perf.sh (always) and runtime-checks.sh (when INCLUDE_RUNTIME=1), invokes the shared emitter with OUTPUT_KIND=performance, and writes both .json and .sarif.

2. Markdown summary (LLM deliverable, NOT automated). Written by the skill in the conversation, ranked by impact, with concrete recommendations. Sample:

   ### High — Catalog\Block\Category::getProducts() N+1 on store frontend
   
   Impact: Each category page render triggers 1+N queries (N = product count).
   Evidence: src/app/code/Acme/Catalog/Block/Category.php:47
   Recommendation: Use addAttributeToSelect(['name','price']) before iteration; or use
   the CollectionProcessor pattern.
   Verification: Re-render the page with debug toolbar; query count should drop from
   1+N to 1.

Builder invocation (for reference; callers normally just run the skill):

TARGET_MODULE=<Vendor_Module|site> TARGET_PATH=<path> SCOPE=module \
SCAN_ROOT={ctx.magento_root}/app/code INCLUDE_RUNTIME=0 \
DOCS_ROOT="${DOCS_ROOT_ARG:-.docs}" \
bash ${CLAUDE_SKILL_DIR}/scripts/build-findings.sh

where DOCS_ROOT_ARG is the resolved --docs-root value (empty ⇒ default .docs).

Inputs

/perf-audit [--runtime] [--scope=module|site] [--docs-root=<path>] [<Vendor>_<Module>...]

Flags:

• --runtime — opt in to runtime checks (Phase 3, 4)
• --scope=site — audit all custom modules + runtime
• --format=markdown|json|sarif — output format
• --docs-root=<path> — output-root override; see "Output Root" below

Outputs

Module scope (basename uses the underscore module name, e.g. Acme_OrderExport):

{output_root}/audits/{Vendor}_{Module}-perf-{date}.json    # automation artifact (build-findings.sh)
{output_root}/audits/{Vendor}_{Module}-perf-{date}.sarif   # automation artifact (build-findings.sh)
{output_root}/audits/{Vendor}_{Module}-perf-{date}.md      # LLM deliverable, written in Phase 5

Site scope:

{output_root}/audits/perf-{scope}-{date}.json
{output_root}/audits/perf-{scope}-{date}.sarif
{output_root}/audits/perf-{scope}-{date}.md

{output_root} (.docs by default, {ctx.docs_root}) is anchored at the project root, never under {ctx.magento_root}, app/code, or a module dir. See the Artifact location rule in context/SKILL.md and the --docs-root/DOCS_ROOT recipe in context/references/artifact-layout.md.

Output root (--docs-root)

This skill accepts --docs-root=<path> (see context/references/artifact-layout.md). When set, run the emitter with DOCS_ROOT=<path> so artifacts land under <path>/audits/; otherwise they default to {ctx.docs_root}/audits/. Orchestrators such as feature pass this to collect a run's artifacts under one folder.

Reference Files

• references/perf-checklist.md — full static-check catalogue.
• references/n-plus-one-patterns.md — known N+1 patterns + remediation.
• references/caching-rules.md — identity, lifetime, tag rules.
• references/indexer-health.md — indexer mode interpretation.
• references/queue-health.md — backlog thresholds, dead-letter handling.
• references/blackfire-integration.md — Blackfire profile parsing.
• references/severity-perf.md — severity calibration anchored to shared scale.

Scripts

• ${CLAUDE_SKILL_DIR}/scripts/static-perf.sh — static pattern scan over module sources.
• ${CLAUDE_SKILL_DIR}/scripts/runtime-checks.sh — bin/magento + redis-cli + mysql probes.
• ${CLAUDE_SKILL_DIR}/scripts/build-findings.sh — aggregate scanner output; emit JSON + SARIF via the shared context/scripts/emit-findings.sh pipeline. Structurally identical to security/scripts/build-findings.sh.
• context/references/findings-schema.md — JSON findings-document structure the emitted .json conforms to (outputKind=performance).

Execution Mode

Default: auto — agents when the plugin's context-budget hook reports this conversation above its threshold, inline otherwise. In agents mode (--agents flag, or execution_mode in .claude/m2.json surfaced as {ctx.execution_mode} — selection contract in context/references/execution-modes.md) the judgement passes of this skill are dispatched to the read-only reviewer agent with a performance/operations dimension brief, and this skill owns synthesis. The scripted scanners (scripts/build-findings.sh) are deterministic and run identically in both modes.

Severity

Use the shared five-point scale (context/references/severity.md) with the performance-specific calibration anchors, the storefront-vs-admin bias, and the profile-backed severity bands in references/severity-perf.md.

Acceptance Criteria

• Runs without Magento CLI; produces static report only.
• Runtime checks gracefully degrade when tools are missing.
• Top-10 findings are actionable with file:line + recommendation.
• JSON output usable in CI for trend detection.

Related Skills