Lighthouse Pagespeed Weapon

lighthouse-pagespeed-weapon

Opinionated playbook for running Lighthouse and PageSpeed Insights correctly — in CI, locally, and as part of a long-term performance tracking strategy. Synthesized from the Lighthouse 12.6.1 + LHCI 0.15.x canon, the web.dev lab-vs-field framework, and 2025-2026 practitioner patterns.

Read first: guides/00-runner-selection.md — the decision tree for which tool to use before you touch any config.

When to use this skill

Load this skill when lighthouse-pagespeed-guardian is invoked. Trigger phrases:

• "Set up Lighthouse CI / LHCI"
• "Add a performance budget to our CI pipeline"
• "My Lighthouse score is 90 but CrUX says I'm failing LCP"
• "Configure Lighthouse for GitHub Actions"
• "What's the difference between TBT and INP?"
• "Compare Treo vs SpeedCurve for monitoring"
• "Write a custom Lighthouse plugin"
• "Audit this URL with Lighthouse"
• "Set a performance budget"

Do NOT load for:

• SEO content strategy, keyword research, or metadata optimization (route to seo-aeo-guardian)
• Core Web Vitals implementation fixes like image optimization or JS bundle reduction (route to react-guardian or performance-optimizer)
• Accessibility design decisions beyond Lighthouse-flagged technical issues
• CI/CD pipeline topology beyond the Lighthouse-specific configuration step (route to devops-guardian)

Critical directives

These are non-negotiables. They protect reproducibility, team trust, and the lab-vs-field mental model.

• Always specify throttling and form-factor explicitly. A mobile simulation at 4x CPU / 1.6 Mbps and a desktop no-throttle run produce completely different scores; mixing them corrupts trend data. See guides/00-runner-selection.md.

• Run at least three passes; report the median. LHCI defaults to three runs for this reason (numberOfRuns: 3). A single Lighthouse run has high variance due to non-deterministic CPU and network simulation. See guides/01-lhci-configuration.md.

• Always present both lab scores and CrUX field data when PSI API data is available. Lab data reflects ideal conditions; field data (p75) reflects real users. The gap between them is often the most actionable signal. See guides/02-lab-vs-field.md.

• Never set a score budget below the current production baseline without a remediation plan. Measure first (lhci autorun without assertions), document baselines, then add a 10-20% buffer. A budget that gates CI on day one with no remediation plan blocks deploys without unblocking the team. See guides/01-lhci-configuration.md.

• TBT is an imperfect proxy for INP. A good TBT does not guarantee a good INP. INP measures full interaction latency (delay + processing + presentation). TBT only captures blocking tasks during load. A page can have TBT < 200ms and INP > 500ms. Always check field INP separately. See guides/02-lab-vs-field.md.

• Scope custom plugins to audits that existing Lighthouse audits cannot cover. Plugins cannot access custom Gatherers; they can only read existing artifacts (ImageElements, ScriptElements, devtoolsLogs, etc.). If you need custom page data, you need a full custom config. See guides/05-custom-plugins.md.

Lighthouse 12 / LHCI 0.15.x facts (encoded from research)

Source: research/external/2026-05-20-lighthouse-performance-scoring.md

Current version: Lighthouse 12.6.1 (LHCI 0.15.x). Node 18+ required.

Four categories (not five — PWA removed in LH12, May 2024):

• Performance
• Accessibility
• Best Practices
• SEO

Performance score weights (unchanged from LH10):

INP is NOT in the Lighthouse Performance score. INP replaced FID as a Core Web Vital (March 12, 2024), but INP is a field-only metric. TBT is its lab proxy. TTI was removed from the score in Lighthouse 10.

Score color bands: 0-49 red (Poor), 50-89 orange (Needs Improvement), 90-100 green (Good). Reaching 90+ means being in the top 8% of HTTP Archive sites for that metric.

Guide map

Each guide is a self-contained instruction set. Read in order on first use; jump directly to the relevant guide for targeted tasks.

Templates

• templates/lighthouserc-starter.yaml — Annotated production-ready LHCI config
• templates/custom-plugin-starter.js — Scaffold for a custom Lighthouse plugin

Examples

• examples/happy-path-lhci-setup.md — End-to-end LHCI setup from zero to CI-gating a Next.js app
• examples/lab-field-reconciliation.md — Walking through a case where Lighthouse scores 90 but CrUX INP fails

Reports

• reports/README.md — Report template and location convention for audit reports

Command Brief: ai-tools/command-briefs/lighthouse-pagespeed-guardian-command-brief.md Research: research/research-summary.md (normal depth, 9 sources, May 2026) Forged by weapon-forge as part of the Legion AI Tools Factory by Mario Aldayuz a.k.a @thenotoriousllama