Investigate Web Perf

Investigate Web Performance Issues

Disciplined, evidence-driven investigation of web app performance problems using chrome-devtools-mcp. This skill is the canonical loop; references are loaded on demand based on the scenario and framework.

Prerequisite: chrome-devtools-mcp and the Chrome DevTools Skills plugin must be installed. If they aren't, stop and run the setup-perf-stack skill first.

The Loop

1. Reproduce deterministically. Pin emulation. Never investigate a "sometimes slow" page without first making it reliably slow.
2. Capture. Record a trace; save to disk, do not stream JSON.
3. Analyze via insights, never raw JSON. Call performance_analyze_insight with a name from the fixed list of 18.
4. Pin root cause to file:line. Use evaluate_script, list_network_requests, list_console_messages, and React DevTools.
5. State a single-variable hypothesis. One change per iteration.
6. Fix. Make the minimum change the hypothesis predicts.
7. Validate. Re-trace under identical emulation. Accept only if the target insight moves ≥10% and no other Core Web Vital regresses. Otherwise revert and re-hypothesize.

Always-Pinned Emulation Profile

Every trace in this skill uses these settings. Do not change them mid-investigation; you lose comparability.

• cpuThrottlingRate: 4
• networkConditions: "Slow 4G"
• Mobile viewport (390×844) unless the user specifies desktop
• Cache-cold loads via new_page + navigate_page, not warm reloads
• Run N=3 and report the median; single runs vary ±15–30%

Tighten only if the user explicitly wants a desktop-class target (e.g., cpuThrottlingRate: 1, networkConditions: "Fast 4G"). Document the deviation in the report.

The 18-Insight Vocabulary

Pass one of these as insightName to performance_analyze_insight. Do not invent names.

Load / paint / rendering:

• DocumentLatency, LCPBreakdown, LCPDiscovery, RenderBlocking
• CLSCulprits, ForcedReflow, SlowCSSSelector

Interaction:

• INPBreakdown, LongCriticalNetworkTree, NetworkDependencyTree

JavaScript / delivery:

• DuplicatedJavaScript, LegacyJavaScript, ModernHTTP

Resources / configuration:

• ThirdParties, FontDisplay, ImageDelivery, Viewport, Cache

Non-Negotiables

1. Always call performance_analyze_insight before writing any custom Perf-API JS. The 18 insights are the complete vocabulary for trace analysis. Custom performance.getEntries*() calls are a last resort, not a first move.
2. Never pass raw trace JSON to the model. Save with filePath: "trace.json.gz" and reference the path. Let the MCP's PerformanceTraceFormatter do the compression (30 MB → ~4 kB, 48 lines).
3. One variable per iteration. Never ship two simultaneous changes and call them a fix — you cannot attribute the delta.
4. Re-trace under identical emulation before claiming a fix. Before/after paths go in the report. No "it feels faster".
5. Reject fixes <10% on the target insight, or any regression elsewhere. Revert and form a new hypothesis.
6. Spawn a subagent per insight drill-down when traces are large. Each subagent returns <5 kB to the main thread. This is the single most effective way to keep the main context clean across a multi-step investigation.
7. Prefer accessibility-tree snapshots over screenshots. Screenshots are ~2k tokens each and rarely carry diagnostic signal for perf work. Reserve them for CLS visual verification and canvas/WebGL issues.

Which Reference to Load

Load on demand — do not read these speculatively. The main SKILL.md (this file) already covers the universal discipline.

By scenario

By framework (load in addition to the scenario reference)

Do not load framework references if the project doesn't use that framework.

Loop Anti-Patterns

Watch for these and correct immediately:

• Skipping insights for custom JS. If the first tool call is evaluate_script with a performance.* API, the agent is doing it wrong. Back up and pick an insight.
• "Let me also try..." Second change before validating the first. Revert.
• Comparing traces with different emulation. The numbers are not commensurable.
• Reporting LCP improved without checking INP/CLS. A "fix" that trades one vital for another is not a fix.
• Talking about the trace without reading the insight output. If the agent is speculating based on code rather than trace evidence, something went wrong in step 2 or 3 — re-capture.

When to Escalate to the User

• Non-determinism persists after N=3 medianing — likely real-user variance (CrUX field injection, thermal throttling, GC). Surface to the user and propose measuring in Sentry/RUM if available.
• Fix requires architectural change (e.g., switching rendering mode, moving to a CDN, adopting streaming SSR). State the hypothesis, estimated impact, and stop. Do not implement silently.
• Dependency upgrade required — confirm with the user before touching package.json.

Reference Index

• references/lcp.md — LCP regression workflow: subpart model, insight sequence, prompt template.
• references/inp.md — INP / slow interaction workflow: Long Animation Frames, presentation split.
• references/rerenders.md — Unnecessary re-renders workflow: react-scan, classification, React DevTools integration.
• references/bundle.md — Bundle bloat workflow: DuplicatedJavaScript/LegacyJavaScript, network filtering, source mapping.
• references/memory.md — Memory leak workflow: heap snapshot comparison, memlab, common leak shapes.
• references/react.md — React-specific rules: memo discipline, useDeferredValue, <Profiler>, RSC streaming gotchas, tool recommendations.
• references/nextjs.md — Next.js-specific rules: Turbopack tracing, instrumentation.ts, RSC payload debugging, next build output parsing.