skilldrop-cli 0.16.35 → 0.16.37

package/packs/frontend/skills/rendering-strategy/reference.md

@@ -0,0 +1,116 @@
+# rendering-strategy reference
+
+## Modes: what each costs and how each fails
+
+| Mode | Renders | Fresh to | Personalised? | Indexed / previews | When the data source fails |
+|---|---|---|---|---|---|
+| Static at build (SSG) | once per build per page | last build | no (fragments only) | yes | page still served; data is as of the build |
+| Revalidated (ISR, stale-while-revalidate, CDN `s-maxage` + `stale-while-revalidate`) | once per window per page that is visited, plus once per on-demand event | window, or the change event if on-demand | no (fragments only) | yes | last good copy keeps serving; regeneration retries |
+| Server per request (SSR) | once per view | the request | yes | yes | TTFB waits on the slowest call; without a timeout the page errors or hangs |
+| SSR streaming | once per view; shell first | the request | yes | yes, for content in the shell | shell arrives; the slow part shows its placeholder or fallback |
+| Edge render | once per view, near the user | the request | yes, from cookie or geo | yes | as SSR, and every data call still travels to the origin region |
+| Client-rendered (CSR, SPA) | none on the server; one data call or more per view | the request | yes | no: crawlers and preview bots get an empty shell | spinner, then an error state; nothing without JavaScript |
+| Islands / server components | per the page's mode; only interactive parts ship JavaScript | per the page's mode | the island can be | yes | per the page's mode; an island can fail alone |
+
+Two rules the table implies:
+
+- **Revalidation reduces renders only when a page gets more views than windows.** A long tail
+  of pages each viewed a few times a month renders about once per view under a 5-minute
+  window. On-demand revalidation on the real change event is the saving.
+- **Edge rendering is not faster when the data is in one region.** The HTML starts near the
+  user and then waits on a round trip to the origin database. It pays off for decisions made
+  from the request alone (geo, cookie, A/B bucket) or data replicated to the edge.
+
+## Splitting a page
+
+| The page has… | Render the page | Render the part |
+|---|---|---|
+| A greeting, avatar or cart count | cached (static or revalidated) | client fetch to a `private, no-store` endpoint after load, or an edge-rendered fragment |
+| A stock, price or seat count that must be fresh within seconds | cached | client fetch to an endpoint with a CDN TTL at or under the tolerance (which also collapses a spike to one origin call per TTL); the authoritative check at checkout |
+| Recommendations per user | cached | client island, lazy, below the fold |
+| A/B variant or locale | cached per variant (variant in the cache key, not a cookie `Vary`) | — |
+| Whole page differs per user (dashboard, orders, settings) | per request or client-rendered, never shared-cached | — |
+
+## Cache headers
+
+- Shared, revalidated HTML: `Cache-Control: public, s-maxage=<window>, stale-while-revalidate=<grace>`.
+- Personalised HTML or JSON: `Cache-Control: private, no-store`. Never rely on `Vary: Cookie` to
+  separate users at a CDN: many CDNs ignore it or it turns the hit rate to zero.
+- A response with `Set-Cookie` is never stored in a shared cache. Check the CDN's default.
+- Query strings: list the parameters that change the content (`?category=`, `?page=`) and strip
+  or ignore tracking ones (`utm_*`, `gclid`) from the cache key. Faceted combinations that
+  explode the key space are rendered client-side from a cached listing, or get `noindex` and a
+  canonical URL.
+
+## Invalidation events
+
+Write each as event → pages:
+
+- Content publish or edit in a CMS → the page, its index and listing pages, the sitemap.
+- Product, price or stock-threshold change in a catalogue system → the product page, its
+  category pages, any page featuring it (home carousel).
+- Deploy → every static page rebuilt; say whether a deploy is the only way a page changes.
+- Time → only for data with no event (exchange rates polled, aggregated counts).
+
+## Framework settings
+
+Use only the section for the framework the user named. Behaviour that changed between major
+versions is marked; confirm the version in `package.json` before stating it.
+
+### Next.js
+
+- **App Router.** Route segment config per route: `export const revalidate = 600` (time-based),
+  `export const dynamic = 'force-static'` or `'force-dynamic'`; `generateStaticParams` to
+  prerender dynamic segments. On-demand: `revalidatePath('/p/slug')` or `revalidateTag('product:123')`
+  from a route handler the webhook calls; tag the fetch with `next: { tags: [...] }`.
+- **The trap:** calling `cookies()` or `headers()` in a layout makes every route under it
+  dynamic. A greeting in the root layout turns the whole site into per-request SSR. Move the
+  personal part into a client component that fetches after load, or behind `<Suspense>`.
+  Reading `searchParams` in a page does the same to that page: filters and sorting as query
+  strings make a listing dynamic. Filter client-side over the cached listing, or make the
+  indexed combinations path segments with `generateStaticParams`.
+- **Version-dependent:** the default caching of `fetch` changed between major versions (cached by
+  default earlier, not cached by default from 15). Partial prerendering and the `"use cache"`
+  directive are experimental in some versions. State the version before relying on any of these.
+- **Pages Router.** `getStaticProps` with `revalidate`, `getStaticPaths` with `fallback: 'blocking'`,
+  `getServerSideProps` for per request, `res.revalidate()` for on-demand.
+
+### Nuxt
+
+- `routeRules` in `nuxt.config`: `{ prerender: true }` (static at build), `{ swr: 600 }` (cached
+  response with background revalidation), `{ isr: 600 }` (the same on hosts with ISR support,
+  such as Vercel or Netlify), `{ ssr: false }` (client-rendered), `{ headers: { 'cache-control': ... } }`.
+- **The trap:** `swr` and `isr` cache the rendered response keyed by path, shared across users.
+  On a personalised path they serve one user's page to everyone. Personalised routes get
+  `{ ssr: false }` or no cache rule plus `private, no-store`.
+- `prerender: true` on a page that changes between deploys freezes it until the next build.
+
+### Remix / React Router (framework mode)
+
+- Rendering is per request by default; caching is the `Cache-Control` the route's `headers`
+  export returns (`public, s-maxage=…, stale-while-revalidate=…` for shared, `private, no-store`
+  for personal). The CDN does the revalidation.
+- Slow data: return the promise from the loader without awaiting it and render it with
+  `<Await>` inside `<Suspense>`, so the shell streams first.
+- **Version-dependent:** React Router 7 adds `prerender` and `ssr: false` in
+  `react-router.config.ts` for static and SPA modes; Remix 2 has neither.
+
+### SvelteKit
+
+- Per route in `+page.js` / `+page.server.js` or a layout: `export const prerender = true`,
+  `export const ssr = false` (client-rendered), `export const csr = false` (no JavaScript at all
+  for a read-only page). `setHeaders({ 'cache-control': ... })` in `load` for CDN caching.
+- ISR is adapter-specific (for example `export const config = { isr: { expiration: 600 } }` on the
+  Vercel adapter); on other adapters use CDN headers.
+- **The trap:** `prerender = true` on a layout applies to every child route, including ones that
+  need the request (cookies, `url.searchParams`); the build errors on them or the personal part
+  is rendered once at build. Set it per route, or override with `prerender = false` below.
+
+### Astro
+
+- Static by default. Per page: `export const prerender = false` to render on request (needs an
+  adapter); site-wide `output: 'server'` flips the default.
+- Islands: `client:load`, `client:idle`, `client:visible` hydrate one component; everything else
+  ships no JavaScript. Server islands (`server:defer`) render a personal fragment per request
+  inside a cached static page — the direct fit for a greeting on a static page.
+- **Version-dependent:** server islands need a version that supports `server:defer`.

package/packs/frontend/skills/rendering-strategy/scripts/render_load.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""Count the page renders each route costs per month under its rendering mode.
+
+Reads a CSV of routes (a path, or "-" for stdin) and prints a Markdown table of
+origin renders per month under the chosen mode beside what per-request SSR
+would cost, so the cost question in a rendering decision is a number, not a
+guess. Stdlib only, Python 3.9+.
+
+CSV columns (header row required; blank cells allowed where noted):
+  route          name of the route, e.g. /products/[slug]
+  mode           ssg | isr | ssr | csr | edge
+  views_month    page views per month for the whole route (all pages)
+  pages          distinct pages the route has (default 1)
+  revalidate_s   isr only: time-based revalidation window in seconds
+                 (blank = on-demand revalidation only)
+  changes_month  ssg/isr: content changes per month that trigger a rebuild or
+                 on-demand revalidation of one page (default 0)
+  builds_month   ssg only: full builds per month (default 0)
+
+Usage:
+  python3 render_load.py routes.csv [-o report.md]
+"""
+
+import argparse
+import csv
+import io
+import sys
+
+MONTH_S = 30 * 24 * 3600
+MODES = {"ssg", "isr", "ssr", "csr", "edge"}
+
+
+def num(row, key, default=None, line=0):
+    raw = (row.get(key) or "").strip().replace(",", "").replace("_", "")
+    if raw == "":
+        if default is None:
+            raise ValueError(f"line {line}: '{key}' is required")
+        return default
+    try:
+        value = float(raw)
+    except ValueError:
+        raise ValueError(f"line {line}: '{key}' must be a number, got '{raw}'")
+    if value < 0:
+        raise ValueError(f"line {line}: '{key}' must not be negative")
+    return value
+
+
+def renders(row, line):
+    mode = (row.get("mode") or "").strip().lower()
+    if mode not in MODES:
+        raise ValueError(f"line {line}: mode must be one of {sorted(MODES)}, got '{mode}'")
+    views = num(row, "views_month", line=line)
+    pages = max(num(row, "pages", 1, line), 1)
+    changes = num(row, "changes_month", 0, line)
+    note = ""
+    if mode == "ssr":
+        origin = views
+        note = "one render per view; TTFB depends on the data source"
+    elif mode == "edge":
+        origin = views
+        note = "one render per view, at the edge; data calls still go to origin"
+    elif mode == "csr":
+        origin = 0
+        note = f"static shell; at least {fmt(views)} client data calls"
+    elif mode == "ssg":
+        builds = num(row, "builds_month", 0, line)
+        origin = builds * pages + changes
+        note = "renders happen at build time, not per view"
+    else:  # isr
+        reval = num(row, "revalidate_s", 0, line)
+        if reval == 0:
+            origin = min(changes, views)
+            note = "on-demand revalidation only"
+        else:
+            windows = MONTH_S / reval
+            per_page = views / pages
+            # each render is triggered by a view, so renders never exceed views
+            origin = min(pages * min(per_page, windows) + changes, views)
+            if per_page <= windows:
+                note = ("upper bound; each page gets fewer views than windows, "
+                        "so time-based revalidation saves little: use on-demand")
+            elif pages == 1:
+                note = "at most one render per window"
+            else:
+                note = "upper bound if traffic is even; skewed traffic renders less"
+    saved = 0.0 if views == 0 else 1 - origin / views
+    return {
+        "route": (row.get("route") or "").strip() or f"(line {line})",
+        "mode": mode,
+        "views": views,
+        "origin": origin,
+        "saved": saved,
+        "note": note,
+    }
+
+
+def pct(saved):
+    if saved <= 0:
+        return "no fewer" if saved == 0 else f"{-saved * 100:.0f}% more"
+    if saved >= 0.995 and saved < 1:
+        return ">99% fewer"
+    if saved < 0.005:
+        return "<1% fewer"
+    return f"{saved * 100:.0f}% fewer"
+
+
+def fmt(n):
+    return f"{int(round(n)):,}"
+
+
+def report(rows):
+    out = [
+        "| Route | Mode | Views/month | Origin renders/month | vs SSR per request | Note |",
+        "|---|---|---:|---:|---:|---|",
+    ]
+    total_views = total_origin = 0.0
+    for r in rows:
+        total_views += r["views"]
+        total_origin += r["origin"]
+        out.append(
+            f"| {r['route']} | {r['mode']} | {fmt(r['views'])} | {fmt(r['origin'])} | "
+            f"{pct(r['saved'])} | {r['note']} |"
+        )
+    saved = 0.0 if total_views == 0 else 1 - total_origin / total_views
+    out.append(
+        f"| **Total** | | {fmt(total_views)} | {fmt(total_origin)} | {pct(saved)} | |"
+    )
+    out.append("")
+    out.append(
+        "Origin renders are upper bounds assuming views spread evenly across a route's pages; "
+        "a 30-day month is used. SSR per request renders once per view."
+    )
+    return "\n".join(out) + "\n"
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("csv", help="routes CSV, or - for stdin")
+    ap.add_argument("-o", "--output", help="write the Markdown report here (default: stdout)")
+    args = ap.parse_args(argv)
+
+    try:
+        if args.csv == "-":
+            text = sys.stdin.read()
+        else:
+            with open(args.csv, encoding="utf-8") as fh:
+                text = fh.read()
+    except OSError as exc:
+        print(f"error: cannot read {args.csv}: {exc}", file=sys.stderr)
+        return 2
+
+    reader = csv.DictReader(io.StringIO(text))
+    missing = {"route", "mode", "views_month"} - set(reader.fieldnames or [])
+    if missing:
+        print(f"error: CSV is missing columns: {', '.join(sorted(missing))}", file=sys.stderr)
+        return 2
+    rows = []
+    try:
+        for i, row in enumerate(reader, start=2):
+            if not any((v or "").strip() for v in row.values()):
+                continue
+            rows.append(renders(row, i))
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    if not rows:
+        print("error: no routes in the CSV", file=sys.stderr)
+        return 2
+
+    text = report(rows)
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as fh:
+            fh.write(text)
+        print(f"wrote {args.output}")
+    else:
+        sys.stdout.write(text)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/packs/frontend/skills/web-performance-review/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: web-performance-review
+description: Read a Lighthouse report or PageSpeed Insights result, with field data when there is any (CrUX, PSI loadingExperience or RUM p75), and say what makes the page slow for real users and what to fix first, ranked by how much each fix moves LCP, INP and CLS at the 75th percentile. Names the LCP element and which LCP phase dominates, the elements that shift and why, the long tasks and third parties by main-thread time, and treats estimated savings as lab estimates that overlap. Use when the user shares a Lighthouse JSON or PSI result and asks "why is this page slow", "what should we fix first", "we score 92 but Search Console says LCP is poor", "did our change fix INP", "review this Lighthouse report", or "how do we pass Core Web Vitals".
+---
+
+# web-performance-review
+
+Reads a Lighthouse run the way a performance engineer does: real-user p75 numbers decide whether
+the page has a problem, and the one lab run explains why. The output names the element, the URL
+and the change, in the order that moves the failing vital most. Accessibility findings in the
+same report go to `accessibility-audit`. What is inside a heavy JavaScript bundle is
+`bundle-size-review`. Choosing SSR, static or client rendering for a route is
+`rendering-strategy`. Setting up RUM or alerting on the vitals is `observability-plan`.
+
+## How to respond
+
+**Four rules come before the steps and outrank them:**
+
+- **Answer what was asked, first.** Open with the answer, the decision or the artifact, in plain words. Scores, matrices, frameworks and tags come after it, and anything that doesn't change the answer is cut.
+- **Use only what you were given.** Don't add facts, names, numbers, incidents, history, steps or sections the input doesn't contain. What you need and don't have is left out of the artifact and listed once at the end under "To confirm".
+- **Deliver from what you have.** When the request gives you something to work on, state your assumptions in a line and produce the result. When it gives you nothing to work on, ask for it in one or two plain sentences and say what you will do once you have it.
+- **Write for someone who has never heard of this skill.** No skill names, no paths or scripts from this folder, no internal terms, and nothing about how the run was set up. A next step is one plain sentence at the end that describes the work.
+- **For this skill:** Field p75 decides whether there is a problem; the lab run explains why. Never call a page good or bad from the Performance score, and say which data each verdict rests on.
+
+1. **Get the report and any field data.** Accept the Lighthouse JSON, a PageSpeed Insights API response (it embeds the Lighthouse result and the CrUX field data), a CrUX API record, or RUM p75 numbers typed in the message. Ask once, in one sentence, for field data when there is none; never hold the review back for it. When the user can run Lighthouse, ask for three to five runs, not one:
+   ```bash
+   for i in 1 2 3 4 5; do npx lighthouse "$URL" --only-categories=performance --output=json --output-path="run-$i.json" --quiet --chrome-flags="--headless"; done
+   ```
+   An installed CLI is the same command without `npx`: `lighthouse "$URL" --output=json --output-path=report.json`.
+
+2. **Run the summary script; read numbers from it, not by eye.** It prints the run settings, lab metrics against thresholds, field p75 with ratings and the Core Web Vitals outcome, the LCP element and phases, layout-shift culprits, failing audits ranked by the vital they move (with overlaps marked), long tasks and third parties, and render-blocking resources. It exits 2 on a file that is not a Lighthouse, PSI or CrUX result.
+   ```bash
+   # Claude Code
+   python3 "${CLAUDE_SKILL_DIR}/scripts/lh_summary.py" psi.json
+   python3 "${CLAUDE_SKILL_DIR}/scripts/lh_summary.py" report.json --lcp-p75 3100 --inp-p75 420 --cls-p75 0.04
+   python3 "${CLAUDE_SKILL_DIR}/scripts/lh_summary.py" before.json after.json
+   # Other IDEs (from the skill folder)
+   python3 scripts/lh_summary.py psi.json --json
+   ```
+   Pass RUM numbers with `--lcp-p75 / --inp-p75 / --cls-p75` and a CrUX file with `--field`. Two reports print a comparability check and the deltas. When only a pasted excerpt is available, apply the same steps by hand and say which sections were not in the excerpt.
+
+3. **Give the verdict from field data, per vital, with the threshold and the source.** Good at p75 is LCP ≤ 2.5 s, INP ≤ 200 ms, CLS ≤ 0.1; poor is LCP > 4 s, INP > 500 ms, CLS > 0.25. Say whether the numbers are for this URL or the whole origin (PSI's `origin_fallback`), and the form factor.
+   - ✅ *"Real mobile users wait 4.3 s for the main image at p75 (poor; good is 2.5 s). The 92 is one simulated lab load, and its 2.4 s LCP is not what users get."*
+   - ❌ *"The page scores 92, so performance is good; LCP could be improved slightly."*
+   - With no field data: ✅ *"Whether the page passes Core Web Vitals can't be told from a lab run. This run shows LCP at 3.1 s in the lab, and here is why."* PSI reports CLS p75 multiplied by 100: `14` is 0.14.
+
+4. **Name the LCP element and fix the phase that dominates.** Quote the element's selector or snippet and split LCP into TTFB, resource load delay, resource load duration and element render delay. The biggest phase picks the fix:
+   - **Load delay** dominates: the browser found the resource late. `loading="lazy"` on the LCP image, no `fetchpriority="high"`, or an image set from JS or a CSS `background-image` (which needs an `<img>` in the HTML, or `<link rel="preload" as="image" fetchpriority="high">`). ✅ *"Remove `loading=\"lazy\"` from `img.collection-hero__image` and add `fetchpriority=\"high\"`; it is in the HTML already, so it needs no preload."* ❌ *"Optimize images."*
+   - **TTFB** dominates: server time, redirects or no HTML caching.
+   - Field TTFB needs improvement or worse while lab TTFB is small: say part of the field LCP is server and network time the lab run can't show. The lab measures one request from one place.
+   - **Load duration** dominates: the file is too large for the viewport (a 2400 px image on a 412 px screen). Name the URL and the `srcset` widths.
+   - **Render delay** dominates: render-blocking CSS or JS, client-side rendering, or long tasks before paint. A text LCP element has no resource, so all of its time is TTFB plus render delay.
+
+5. **Name what shifts and why.** For each shifting element give its score and the cause the report gives: unsized image → `width`/`height` or `aspect-ratio`; web font → `font-display` plus a size-adjusted fallback; injected iframe or banner → reserve the slot with `min-height`. A lab run sees only shifts during load. When field CLS is worse than lab CLS, say the extra comes from shifts after load (scrolling, late banners, ads) that this report can't show, and say what would show them.
+
+6. **Treat TBT as a lab proxy for INP, never as INP.** Name the long tasks by script and the third parties by entity with their main-thread and blocking time: ✅ *"ChatterBox's loader.js: one 170 ms task at 3.1 s; 412 ms of main-thread time in total."* When field INP is good, TBT is not a priority, whatever the score weights say. When field INP is poor, point at the scripts that run on interaction too, because a navigation run records no interactions.
+
+7. **Rank fixes by the failing vital they move, and how much.** Fixes for the vital furthest past its field threshold come first, even when the script's table lists another first. Within a vital, use the audit's per-metric saving (`metricSavings`), not the headline "Est savings", which is lab load time. An audit with a big load saving and no LCP, TBT or CLS saving goes last or is left out: ✅ *"Converting the product-grid JPEGs saves 1.2 MB but does not move LCP; the LCP image is the hero."* Savings that touch the same resource overlap: never add them into a total. Give each fix as the change, on the named element or URL, and the vital it moves.
+
+8. **Say how sure the numbers are.** One run is noisy: say so once, name the emulated device and throttling (Lighthouse's default mobile is a mid-range phone on slow 4G with 4x CPU slowdown), and note any run warnings. Before calling a change an improvement, ask for the median of 3 to 5 runs per side with the same settings, then field data. Runs with different device, throttling or Lighthouse version are not comparable, and the script lists every such difference. CrUX is a 28-day rolling window, so it trails a fix by weeks; RUM shows it sooner.
+
+9. **Write the reply in this order.** First, two or three sentences: whether real users have a problem, on which vital, and the main cause. Then up to five numbered fixes, each with the change, where, the vital it moves and the evidence. Then one short paragraph on what this report can't tell. Add "To confirm" only for missing inputs. Leave out the metric tables unless the user asked for them, keep a chat question to a chat-length answer, and keep to any word limit the user sets.
+
+**Non-interactive runs** (subagent, CI, headless): missing field data becomes `[assumption] no field data given; Core Web Vitals pass/fail not stated, lab findings only`, stated first. A missing report, a report with `runtimeError`, or a file the script rejects emits `BLOCKED: need the Lighthouse JSON (lighthouse <url> --output=json) or the PageSpeed Insights API response for the page`. Never review a report that failed to load the page.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md): thresholds, the Lighthouse and PSI fields read, LCP phases and their fixes, CLS causes, audit-to-vital map, throttling presets, field-data quirks
+- [`scripts/lh_summary.py`](scripts/lh_summary.py): stdlib summariser for Lighthouse, PSI and CrUX JSON; `--json`, `-o`, two-report comparison; exits 2 on bad input
+- [`examples/quayside-article.md`](examples/quayside-article.md): worked example, a news article with poor field CLS from an ad slot and a TTFB-heavy LCP
+
+## Quality bar
+
+- **The first lines say whether real users have a problem**, on which vital, from which data, with the p75 threshold.
+- **No verdict from the Performance score.** The score is described as a lab weighting, not as Core Web Vitals.
+- **The LCP element is named** by selector or snippet, with the phase breakdown when the report has it, and the fix matches the dominant phase.
+- **Every CLS fix names the shifting element and its cause**; field CLS above lab CLS is called out as after-load shifts the run can't see.
+- **TBT is never reported as INP.** Long tasks and third parties are named by script or entity with milliseconds.
+- **Fixes are ranked by the failing vital's per-metric saving**, load-time-only savings are not ranked as vital fixes, and overlapping savings are not summed.
+- **The single-run caveat and the emulated device and network appear once**, with medians of 3 to 5 runs or field data as the bar for "improved".
+- **No invented numbers, elements or URLs.** Every figure and selector is in the input or computed from it.
+
+## When to use this skill
+
+- ✅ A Lighthouse JSON or PSI result is shared with "why is this slow" or "what do we fix first"
+- ✅ The lab score and Search Console or CrUX disagree
+- ✅ Checking whether a performance change worked, from before and after runs
+- ✅ Planning Core Web Vitals work for a page from its report and RUM numbers
+
+## When NOT to use this skill
+
+- ❌ The accessibility findings in the same Lighthouse report: use `accessibility-audit`
+- ❌ What is in a JavaScript bundle and why it is heavy (source maps, stats files): use `bundle-size-review`
+- ❌ Choosing SSR, static, ISR or client rendering for routes: use `rendering-strategy`
+- ❌ Setting up RUM, web-vitals collection, dashboards or alerts: use `observability-plan`
+- ❌ Lighthouse SEO and Best Practices scores; this skill reads the Performance category only
+
+## Anti-patterns to avoid
+
+- ❌ **"92, so it's fine."** The score weights one simulated load; it says nothing about users on slower phones and networks.
+- ❌ **Calling TBT "INP".** A load run has no clicks or taps. INP comes from field data.
+- ❌ **Leading with the biggest "Est savings".** It is page load time in the lab, often for images below the fold.
+- ❌ **Adding savings up.** "Fix these four for 5.9 s" double-counts the same images and the same main thread.
+- ❌ **Preloading a lazy-loaded hero.** The fix is removing `loading="lazy"` and adding `fetchpriority="high"`; a preload on top works around the attribute and leaves the cause in the markup.
+- ❌ **A generic checklist.** "Minify CSS, use a CDN, enable compression" with no element, URL or number from the report.
+- ❌ **"Fixed" after one better run.** Run-to-run variance, a different device or throttling, or a different Lighthouse version can move the score as much as the change did.

package/packs/frontend/skills/web-performance-review/evals/eval_queries.json

@@ -0,0 +1,38 @@
+[
+  {
+    "query": "Here's our Lighthouse JSON for the product page, why is it slow and what should we fix first?",
+    "should_trigger": true
+  },
+  {
+    "query": "PageSpeed says 92 but Search Console says LCP is poor on mobile. Which one is right?",
+    "should_trigger": true
+  },
+  {
+    "query": "We deferred the analytics scripts and the Lighthouse score went up 12 points. Did that fix INP?",
+    "should_trigger": true
+  },
+  {
+    "query": "Review this PSI result and tell me how to get the homepage passing Core Web Vitals",
+    "should_trigger": true
+  },
+  {
+    "query": "What is the LCP element in this Lighthouse report and why is load delay so high?",
+    "should_trigger": true
+  },
+  {
+    "query": "Lighthouse flagged contrast and missing labels on the checkout form, can you audit it against WCAG?",
+    "should_trigger": false
+  },
+  {
+    "query": "Our main.js is 1.4 MB, here's the webpack stats file, what's making it so big?",
+    "should_trigger": false
+  },
+  {
+    "query": "Should the blog and product pages be SSR or static with revalidation in Next.js?",
+    "should_trigger": false
+  },
+  {
+    "query": "Set up real-user monitoring and alerts for Core Web Vitals across our site",
+    "should_trigger": false
+  }
+]

package/packs/frontend/skills/web-performance-review/evals/evals.json

@@ -0,0 +1,76 @@
+{
+  "skill_name": "web-performance-review",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Our marketing lead says the raincoats collection page is fine because PageSpeed gives it 92 on mobile, but Search Console keeps flagging LCP as poor. Here's the PageSpeed Insights API response: psi.json. What's actually making it slow and what should the team fix first?",
+      "assertions": [
+        "Opens by saying real mobile users do have a problem: field LCP at p75 is 4.3 s, which is poor against the 2.5 s threshold, and that the 92 is a lab score from one run rather than a Core Web Vitals verdict",
+        "Names the LCP element as img.collection-hero__image (the raincoats hero image) and identifies that it has loading=\"lazy\", with resource load delay (about 1.19 s, half of the lab LCP) as the largest phase",
+        "Makes removing loading=\"lazy\" from the hero image and adding fetchpriority=\"high\" the first fix",
+        "Does not rank 'Serve images in next-gen formats' (est. 2.85 s / 1,240 KiB) as an LCP fix, and says it covers the product-grid images and has no LCP saving",
+        "Reads field CLS as 0.14 (needs improvement), not 14, notes it is higher than the lab CLS of 0.04 so some shifts happen after load and are not in this run, and names the unsized product-card images or the late web font as the culprits the run does show",
+        "Does not make TBT, long tasks or the third-party scripts a top priority, because field INP is 168 ms, which is good",
+        "Does not add the estimated savings of different audits into a total, and mentions that this is a single lab run on an emulated mid-range phone with slow 4G",
+        "Does not invent metrics, elements, URLs or field numbers that are not in psi.json"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "We deferred the ChatterBox chat widget on the Fernhill autumn-lights event page until after load, and Lighthouse went from 58 to 71. Before the change our RUM had INP at p75 = 380 ms on mobile. Did we fix our INP problem? Runs attached: before.json (before the change) and after.json (after).",
+      "assertions": [
+        "Answers in the first lines that these runs do not show INP is fixed",
+        "Points out the two runs are not comparable because after.json was run with a 2x CPU slowdown and before.json with 4x, so part or all of the TBT and score change comes from the settings",
+        "States that TBT is a lab proxy and not INP, that a load run records no interactions, and that the check is RUM INP p75 after the change against the 200 ms threshold (380 ms was needs improvement)",
+        "Says each side is a single run and recommends the median of 3 to 5 runs per side with identical settings",
+        "Confirms ChatterBox no longer appears in the after run's long tasks or third-party list, so the deferral did take it out of the load",
+        "Names the first-party seatmap.4f2a91.js as the largest remaining long task (620 ms before, 410 ms after at 2x CPU) and the likely next target for INP work",
+        "Does not invent RUM or field numbers for the period after the change"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Quick one for the Slack thread, under 200 words please. Lighthouse mobile gives the Lumen Ledger pricing page a 48 — are we failing Core Web Vitals? What I can see in the report: Performance 48. FCP 3.2 s, LCP 6.8 s, TBT 1,450 ms, CLS 0.02, Speed Index 5.9 s. LCP element: <div class=\"pricing-hero\" style=\"background-image:url(/img/pricing-hero.jpg)\">. LCP breakdown: TTFB 380 ms, Load Delay 4,900 ms, Load Time 1,100 ms, Render Delay 420 ms. Opportunities: Reduce unused JavaScript, est savings 2.9 s; Eliminate render-blocking resources, est savings 1.1 s. Third-party: HelpDock 980 ms main-thread time.",
+      "assertions": [
+        "Says that whether the page passes or fails Core Web Vitals cannot be told from a lab run alone, and that field data at p75 (Search Console, CrUX or PageSpeed field data, or RUM) is needed",
+        "Does not present TBT 1,450 ms as INP; calls it a lab proxy",
+        "Identifies the LCP element as the CSS background image on div.pricing-hero and resource load delay (4.9 s of 6.8 s) as the dominant phase",
+        "Recommends making the hero image discoverable early: an <img> in the HTML with fetchpriority=\"high\", or a preload of /img/pricing-hero.jpg with fetchpriority=\"high\"",
+        "Does not add the 2.9 s and 1.1 s savings into a combined figure, and does not claim the unused-JavaScript saving moves LCP by 2.9 s",
+        "Mentions that this is one lab run on emulated mobile",
+        "Does not invent numbers, elements or field data not in the message",
+        "Stays under 200 words"
+      ]
+    },
+    {
+      "id": 4,
+      "held_out": "2026-10-20",
+      "prompt": "hey, quick one. attached the PSI run for our jacket PDP from this morning (psi-pdp-mobile-2026-10-19.json) plus two exports from our RUM tool (rum-inp-daily.csv and rum-inp-attribution-oct14-19.csv). we shipped the 'defer chatnest until after load' change on oct 13 and lighthouse went 78 -> 91, TBT 640 -> 290. PM wants to close the INP ticket today. search console still says INP poor but i assume that's just lag?? did our change fix INP or not, and if not what do we do next",
+      "assertions": [
+        "Answers the actual question up front: the change helped but did not fix INP, so the ticket should not be closed. It cites the RUM daily file, where PDP mobile INP p75 drops from roughly 539-580 ms (Oct 6-12) to roughly 459-481 ms (Oct 14-19). That is still above the 200 ms 'good' threshold (in the needs-improvement band).",
+        "Explains that the Lighthouse score and TBT gains (78 -> 91, 640 -> 290 ms) cannot show INP is fixed, because a lab navigation run has no user interactions and does not measure INP. TBT is only a load-time proxy.",
+        "Points out that the PSI field data has origin_fallback: true, so the INP p75 of 540 ms is for the whole fernhollow-outfitters.example origin, not this PDP URL. It also notes that CrUX/Search Console use a rolling 28-day window that is mostly from before the Oct 13 deploy, so they cannot confirm or refute the change yet. Lag is only part of the explanation.",
+        "Names button.add-to-cart as the main remaining INP problem (inp p75 486 ms, 4120 interactions). Its processing time dominates (processing p75 362 ms vs input delay p75 38 ms), and it is attributed to pdp-cart.8c1e.js. The fix offered is to shorten or split that handler, e.g. yield to the main thread, paint the feedback first and defer the non-visual work.",
+        "Uses the attribution data correctly: input delay on add-to-cart is small, so ChatNest contention is no longer the main cause there. It still flags that the ChatNest launcher interaction is poor (610 ms p75, input delay 290 ms, though only 520 interactions), and that ChatNest was deferred, not removed (820 ms main-thread time and two long tasks after TTI in the lab run).",
+        "Keeps the focus on INP. It does not lead with LCP, render-blocking CSS or the unused-JavaScript opportunity, and if it mentions them it says they do not bear on the INP question.",
+        "Gives a concrete way to verify the next fix: watch the RUM INP p75 per day and per target after deploying, and check CrUX/Search Console again once a full 28-day window has passed since the fix. Any lookup that needs the network (PSI/CrUX API, Search Console) is written as a command or step for the user, not reported as a result.",
+        "Invents nothing. Every number, selector, script URL, entity name and date it cites appears in the three provided files or the prompt, and it does not claim a URL-level CrUX value or post-deploy CrUX figures that the files do not contain."
+      ]
+    },
+    {
+      "id": 5,
+      "held_out": "2026-10-20",
+      "prompt": "Our agency, Brightline Digital, ran Lighthouse on the Quillstack homepage (lighthouse-home-mobile.json) and is proposing a three-week code-splitting project, because the top opportunity in the report is \"Reduce unused JavaScript\" with estimated savings of 1.9 s. Search Console shows the homepage failing Core Web Vitals on mobile. I've also pulled the CrUX API record for the page (crux-home-phone.json). Before I sign the SOW: will that project get us passing Core Web Vitals? If not, what should we fix instead? I'll forward your answer to our VP of Marketing, so please keep it short and non-technical where you can.",
+      "assertions": [
+        "Answers directly at the start: no, the unused-JavaScript project will not get the homepage passing Core Web Vitals. The field data fails only on CLS (p75 0.27, poor, above 0.25), while LCP p75 is 2100 ms and INP p75 is 160 ms, both already 'good'.",
+        "Explains that the 1.9 s figure is a lab estimate tied to load metrics (the report lists FCP 900 / LCP 1050 metric savings) and does nothing for layout shift. It also notes that Lighthouse's estimated savings overlap (for example with render-blocking-resources' 620 ms on FCP/LCP), so they cannot simply be added up.",
+        "Names the biggest shift correctly. The element that moves is body > main#content (score 0.091), and it moves because the late TallyConsent cookie banner (cdn.tallyconsent.example/v2/banner.js) is inserted above it; the banner itself is not the shifted element. The fix offered is to render the banner as a fixed or bottom overlay, or to reserve its space up front.",
+        "Names the second shift: section.hero > h1 (0.038), caused by the web font northwind-sans-bold.woff2 loading. It notes that the passing font-display audit (text visible with swap) does not prevent this shift, and recommends preloading the font and/or matching the fallback font's metrics (size-adjust / ascent-override), or using font-display: optional.",
+        "Ranks the fixes by CLS impact: cookie banner first, web font second, and the unsized Brightmoor logo image in ul.logo-strip (0.011, also flagged by unsized-images) last as a small width/height or aspect-ratio fix.",
+        "Notes that lab CLS (0.14) understates the field p75 (0.27), so a good Lighthouse number after the fix does not prove the page passes. Success should be confirmed in field data (CrUX's 28-day window, collection period here Sep 19 - Oct 16, or RUM), which takes up to about four weeks to show.",
+        "Is sized for forwarding to a VP: a short answer (roughly under 300 words, or a few bullets) in plain language. It is not an audit of every Lighthouse item, and it does not dwell on the 0.68 performance score, which is not what Core Web Vitals assessment uses.",
+        "Invents nothing. Every metric, selector, URL, vendor name and date it cites appears in lighthouse-home-mobile.json, crux-home-phone.json or the prompt, and it does not give made-up effort estimates or post-fix CLS numbers as if they were measured."
+      ]
+    }
+  ]
+}