kevinpatrickrobbins/codebase-audit/pagespeed-audit

PageSpeed Audit

Fetch real PageSpeed Insights data, trace each finding to the codebase, and produce a prioritized action plan: quick wins applied (or listed) immediately, larger efforts written as tickets.

Reference: references/audit-mappings.md maps every Lighthouse audit ID to investigation commands and fix guidance. Load it before investigating findings.

Workflow

0. Resolve inputs

If not provided in $ARGUMENTS, ask:

• URL to audit (required)
• Project directory (optional — defaults to current working directory)
• Mode: report (findings only) or fix (apply quick wins immediately)

Default mode is report if not specified.

1. Fetch PageSpeed data

Run the fetch script (both mobile and desktop):

python <skill-root>/scripts/fetch_pagespeed.py <url>

The script reads PAGESPEED_API_KEY from the environment if set. Without a key it still works but is rate-limited. Output is JSON with mobile and desktop keys.

2. Parse and present scores

From the JSON output, build a summary table:

                  Mobile    Desktop
Performance         --        --
Accessibility       --        --
Best Practices      --        --
SEO                 --        --
 
Core Web Vitals (Mobile)
  LCP:    Xs   [Good / Needs Improvement / Poor]
  CLS:    X    [Good / Needs Improvement / Poor]
  INP:    Xms  [Good / Needs Improvement / Poor]
  FCP:    Xs
  TBT:    Xms
  SI:     Xs
 
Field Data (real users, if available):
  LCP p75: X  CLS p75: X  INP p75: X

Score convention: 90-100 Good, 50-89 Needs Improvement, 0-49 Poor.

Show mobile scores primarily (Google uses mobile-first indexing). Note if desktop differs significantly.

3. Load audit mappings

Read references/audit-mappings.md now. It contains investigation commands and fix patterns for every audit ID returned by Lighthouse.

4. Investigate the codebase

For each failing opportunity and diagnostic (score < 0.9), use the investigation commands from the mappings reference to check whether the issue exists in the project.

Work through findings in impact order (lowest score / highest estimated savings first).

For each finding, state:

• Confirmed in code: yes / no / partial
• Location: file path(s) where the issue was found
• Evidence: the specific code or config that causes it

Skip investigation if no project directory is available — note this in the report.

5. Classify and prioritize

Split confirmed findings into two buckets using the classification table in references/audit-mappings.md:

Quick Fixes — safe to apply in < 2 hours, low regression risk:

• Image priority prop missing on hero
• Missing <link rel="preconnect">
• <img> tags replaceable with next/image
• font-display not set / missing next/font
• GIFs replaceable with <video>
• compress: false in next.config
• Below-fold images without lazy loading
• Missing sizes prop on <Image>

Tickets — need planning, profiling, or carry regression risk:

• Bundle splitting / unused JS
• Server-side caching / TTFB
• Tailwind purge / unused CSS audit
• Third-party script facades
• DOM virtualization
• INP (requires DevTools profiling session)

6. Output the report

## PageSpeed Audit — <url>
Audited: <date>  Strategy: mobile + desktop
 
### Scores
[table from step 2]
 
### Core Web Vitals
[CWV summary with pass/fail status]
 
### Quick Fixes (<N items)
For each: audit name | file/line | what to change | expected impact
 
### Tickets (<N items)
For each: audit name | why it's a ticket | investigation starting point | effort S/M/L
 
### Passed Audits
[brief list of what's already working]

7. Apply fixes (fix mode only)

In fix mode: apply each Quick Fix one at a time, confirm with the user before each change, then suggest re-running the audit to verify score improvement.

In report mode: list Quick Fixes as ready-to-apply but do not touch files.

Notes

• If the API returns no field data (CrUX), note "Lab data only — no real-user data available for this URL."
• If both mobile and desktop fail on the same audit, the fix is usually the same code path.
• PageSpeed scores fluctuate ~5 points between runs — a 1-2 point change is noise.
• next/image and next/font solve a large fraction of Next.js performance issues — check these first.
• For TTFB issues, look for getServerSideProps or un-cached fetch() in server components.