Lighthouse Pagespeed Stinger

---
name: "lighthouse-pagespeed-stinger"
description: "Runs Lighthouse and PageSpeed Insights for React/Next.js: CI setup (LHCI), audit categories, performance budgets, lab-vs-CrUX gap. Use when setting up or debugging Lighthouse CI."
---

# lighthouse-pagespeed-stinger

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-worker-bee` 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-worker-bee`)
- Core Web Vitals implementation fixes like image optimization or JS bundle reduction (route to `react-worker-bee` or `performance-optimizer`)
- Accessibility design decisions beyond Lighthouse-flagged technical issues
- CI/CD pipeline topology beyond the Lighthouse-specific configuration step (route to `devops-worker-bee`)

---

## 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):**

| Metric | Weight |
|--------|--------|
| Total Blocking Time (TBT) | 30% |
| Largest Contentful Paint (LCP) | 25% |
| Cumulative Layout Shift (CLS) | 25% |
| First Contentful Paint (FCP) | 10% |
| Speed Index (SI) | 10% |

**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.

| Guide | When to read |
|-------|-------------|
| `guides/00-runner-selection.md` | First: before choosing any tool |
| `guides/01-lhci-configuration.md` | Setting up `lighthouserc.json`/yaml, `collect`/`assert`/`upload` |
| `guides/02-lab-vs-field.md` | Reconciling Lighthouse scores vs CrUX / PSI field data |
| `guides/03-ci-integration.md` | GitHub Actions workflow, LHCI setup, score gating |
| `guides/04-performance-tracking.md` | Treo, SpeedCurve, self-hosted LHCI server |
| `guides/05-custom-plugins.md` | Authoring custom Lighthouse audit plugins |
| `guides/06-audit-category-glossary.md` | Understanding individual audits and their score weights |

---

## 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-worker-bee-command-brief.md`*
*Research: `research/research-summary.md` (normal depth, 9 sources, May 2026)*
*Forged by `stinger-forge` as part of The Hive by [Mario Aldayuz a.k.a @thenotoriousllama](https://github.com/thenotoriousllama)*