zz41354899/lighthouse-audit/site-performance-investigator

Site Performance Investigator

Audit a page or project against a Lighthouse Performance target, explain measured bottlenecks, and connect findings to source code when available. Use 90 as the target if the user does not specify one; treat 100 as a stretch target when requested. An audit request authorizes measurement and review. Change code, deployment, or CI only when the user also asks for it. Write the report in the user's language.

Choose the input

• URL: Audit the deployed page. Without source access, identify affected resources and likely causes, but label source-level explanations as hypotheses.
• Project: Inspect its build, run instructions, dependencies, and route entry points. Serve a production build locally and audit representative routes and devices. Map confirmed bottlenecks to relevant source files and lines; inspect route-reachable code for risks a navigation run may miss. If it cannot be run, perform a static performance review and state that no Lighthouse measurement was made. Do not present a development-server score as a production baseline.
• Existing Lighthouse JSON: Read the reports directly. Group only runs with comparable URL, device, Lighthouse/Chrome versions, and settings. Do not require Chrome for this path.

For a new measurement, read methodology and report requirements. For performance diagnosis, read the audit playbook. When project source is available, identify its rendering mode and route-reachable dependencies, then consult only the relevant sections of framework and JavaScript guidance. Apply the shared checks to frameworks not named there. Use the Markdown report template for a full project audit, replacing or removing every placeholder.

Run Lighthouse

Use the official Lighthouse CLI, not a bundled wrapper. Check its current help for available flags. For example, from a temporary output directory:

npx --yes lighthouse@latest https://example.com \
  --output=json --output=html --output-path=./run-01 \
  --chrome-flags="--headless=new" --quiet

Use --preset=desktop for desktop runs; the default is mobile. Make several runs (normally five) with the same settings and unique output paths. Keep the raw JSON and HTML. Record the exact Lighthouse and Chrome versions from the results and browser. Choose an output directory outside the audited project's tracked files unless the user asks to save the artifacts there.

Before accepting results, check runtimeError, final URL, screenshot or rendered page, and whether an error or login page was measured. Report median, minimum, maximum, and individual values for LCP, TBT, CLS, FCP, Speed Index, and performance score. Use the report's configSettings to describe device and throttling. Treat estimated savings as hypotheses until a comparable rerun confirms an improvement.

For each measured route and device, check whether WebP or AVIF images were actually served and whether image delivery contributes to LCP or transfer cost. Follow the image-delivery checks and report the observed formats; absence of WebP alone is not a Lighthouse failure.

Decide whether the target is met

Compare the displayed Lighthouse Performance score for each measured route and device, not the other category scores. Mark a route/device as meets when every valid run reaches the requested score, variable when its median reaches the score but at least one run falls below it, and below target when its median is lower. A project meets the sampled target only when every selected route/device meets it; list any unmeasured routes separately. Static review alone has no score verdict. A measured 100 is an observation under these conditions, not a promise of a stable 100 or a guarantee about real users.

For a project compliance check, give the verdict and a full report using report requirements, unless the user asks for a brief answer. Prioritize recommendations by measured bottleneck and source evidence, identify likely tradeoffs, and state how to verify each change. If the user asks you to optimize the project, implement supported fixes, verify affected behavior, and repeat comparable Lighthouse runs until the target is met or no further safe, evidence-backed changes are available. Report the remaining gap without inventing a score improvement.

For project audits, save the full report as a new Markdown file at the user's requested location, or at a user-accessible location you identify, and link it in the response. Keep measured failures separate from latent source-code risks. A latent risk needs a relevant source path and a plausible route or interaction path plus a concrete test that would confirm it. A package listed in package.json or a generic framework pattern alone is not a finding. Do not estimate score gains from static review.

Boundaries

• Audit public pages or locally served pages without passing cookies, tokens, private headers, or credential-bearing URLs to Lighthouse.
• Separate lab results from CrUX or RUM field data; mark field data unavailable when it was not obtained. A Lighthouse score does not establish real-user experience.
• Do not optimize for the Lighthouse user agent, disable real functionality, or trade away accessibility to raise a score.
• If asked to fix an issue, preserve a comparable baseline, make the narrowest supported change, test affected behavior, and rerun with the same environment. Explain when results are not directly comparable.