| name | trace-audit |
| description | Analyze a Chrome DevTools Performance trace JSON file for performance anomalies, producing a structured audit report with critical issues, warnings, metrics, timeline hotspots, and actionable recommendations. |
| user-invocable | true |
| argument-hint | <trace-file.json> |
Chrome DevTools Trace Audit
Analyze a Chrome DevTools Performance trace and produce a comprehensive performance audit report.
Usage
/trace-audit <path-to-trace.json>
The argument is the absolute path to a Chrome DevTools trace JSON file (exported from the Performance panel).
Workflow
Follow these steps in order. Use parallel tool calls wherever noted.
Step 1 — Validate the trace file
Read the first 100 lines of the file using the Read tool. Confirm it is a valid Chrome DevTools trace by checking for:
- A top-level
traceEvents array, or a bare JSON array starting with [
- Event objects with
name, cat, ph, ts fields
- Presence of
__metadata or TracingStartedInBrowser events
If validation fails, tell the user this doesn't appear to be a Chrome DevTools trace and stop.
Step 2 — Extract metadata
Use Grep on the trace file to extract (run these in parallel):
- Site URL — grep for
TracingStartedInBrowser or navigationStart or FrameCommittedInBrowser and look for a URL in the args
- Process names — grep for
process_name or thread_name to identify renderer, browser, GPU processes
- Trace time range — grep for the first and last
"ts": values to compute trace duration
Step 3 — Run detection passes
Refer to detection-heuristics.md for the full set of patterns and thresholds. Run all detection categories in parallel using Grep. For each category:
- Use the specified grep pattern on the trace file
- Collect matching lines with surrounding context where helpful (
-C 1 or -C 2)
- Count matches and extract durations/values from the matched JSON
The detection categories are:
- Long Tasks (
RunTask with dur > 50000)
- Layout Thrashing (
InvalidateLayout → Layout pairs)
- Forced Reflows (
Layout events with stackTrace)
- rAF Ticker Loops (
RequestAnimationFrame frequency)
- Style Recalc Storms (
UpdateLayoutTree with dur > 5000)
- Paint Storms (
Paint events with dur > 3000)
- GC Pressure (
MajorGC / V8.GC_MARK_COMPACTOR)
- CLS (
LayoutShift cumulative score)
- INP (
EventTiming max duration)
- Network Errors (
ResourceReceiveResponse with statusCode >= 400)
- Redundant Fetches (same URL fetched multiple times)
- Script Eval (
EvaluateScript / CompileScript with dur > 50000)
- Long Animation Frames (
LoAF / LongAnimationFrame)
Step 4 — Aggregate findings
For each detection category:
- Compute total count of flagged events
- Extract the worst offender (max duration or highest score)
- Classify severity: Critical (red) or Warning (yellow) based on the thresholds in
detection-heuristics.md
- Skip categories with zero findings
Step 5 — Identify timeline hotspots
Group flagged events by timestamp into time windows (e.g., 500ms buckets). Identify windows where multiple issue categories overlap — these are hotspot ranges that represent the most problematic sections of the trace.
Step 6 — Generate report
Output the report using the structure defined in report-format.md. The report should be:
- Actionable — every issue links to a concrete fix
- Scannable — use tables, severity badges, and clear headings
- Complete — cover all categories, even if just to say "no issues found"
