@raishin/vanguard-frontier-agentic 3.0.1 → 3.1.0

package/skills/frontend/bundle-budget-code-splitting-review/references/bundler-chunking-apis.md

@@ -0,0 +1,116 @@
+# Bundler Chunking APIs
+
+Use this reference when prescribing or reviewing chunking configuration for Vite, webpack, or Rollup. Every claim below was confirmed against Context7-indexed official documentation as of this skill's `updated` date; re-verify against the installed bundler major before use — see the Context7 Documentation Protocol in `SKILL.md`.
+
+> Version note: bundler chunking surfaces are actively evolving (Vite's Rolldown migration in particular). Verify the installed major version before applying any snippet in this file to a real project.
+
+## What people get wrong
+
+The naive story is:
+
+> "manualChunks is the Vite way to split vendor code, and that's stable."
+
+Wrong, as of Vite 8. Confirmed via Context7 against `/vitejs/vite`'s migration guide: the **object form** of `build.rollupOptions.output.manualChunks` is removed entirely in Vite 8 (Rolldown-powered), and the **function form** is deprecated. Handing a Vite 8+ project the classic object-form snippet produces a config that silently does not apply the intended grouping.
+
+## Vite: manualChunks → codeSplitting
+
+**Deprecated / removed (pre-Vite-8 object form — removed in Vite 8):**
+
+```javascript
+// Vite <8, object form — REMOVED in Vite 8
+build: {
+  rollupOptions: {
+    output: {
+      manualChunks: {
+        vendor: ['react', 'vue'],
+      },
+    },
+  },
+},
+```
+
+**Deprecated but still functional (function form, pre-Vite-8 and transitional):**
+
+```javascript
+// Still works pre-Vite-8; deprecated, flag as a forward-migration item
+manualChunks(id) {
+  if (id.includes('some-heavy-lib')) {
+    return 'heavy-lib-chunk'
+  }
+},
+```
+
+**Current documented replacement (Vite 8+, Rolldown):**
+
+```javascript
+build: {
+  rolldownOptions: {
+    output: {
+      codeSplitting: {
+        groups: [
+          { name: 'vendor', test: /[\\/]node_modules[\\/]/ },
+        ],
+      },
+    },
+  },
+}
+```
+
+Decision rule: confirm the installed Vite major first.
+- Vite 8+: use `rolldownOptions.output.codeSplitting.groups`. Do not offer the object-form `manualChunks` snippet — it does not apply.
+- Vite <8: function-form `manualChunks(id) {...}` is valid today but is a deprecated pattern; note the future migration to `codeSplitting` as a forward-looking item rather than presenting it as the long-term answer.
+
+## webpack: splitChunks / cacheGroups
+
+Confirmed via Context7 against `/websites/webpack_js` guides (caching, printable, code-splitting). This surface is comparatively stable across recent majors, but `chunks` defaults and `cacheGroups` shape still depend on the installed major — confirm before prescribing.
+
+**Vendor chunk extraction:**
+
+```javascript
+optimization: {
+  runtimeChunk: 'single',
+  splitChunks: {
+    cacheGroups: {
+      vendor: {
+        test: /[\\/]node_modules[\\/]/,
+        name: 'vendors',
+        chunks: 'all',
+      },
+    },
+  },
+},
+```
+
+Notes:
+- `chunks: 'all'` makes both synchronously and dynamically imported modules eligible for the cache group; the webpack default for `optimization.splitChunks.chunks` (when not explicitly set) is `'async'`, which only splits dynamically imported modules. Confirm which behavior the review target actually wants — a review that recommends `cacheGroups` without checking the effective `chunks` mode can silently miss the synchronous-import case.
+- Merging all of `node_modules` into a single `vendors` chunk (as shown) is explicitly called out in webpack's own guidance as not generally recommended for typical apps — it produces a single large chunk that invalidates entirely on any dependency bump. Prefer scoping `cacheGroups` to specific heavy dependencies over a single monolithic vendor bucket unless the project's caching strategy specifically wants long-term vendor-chunk stability at the cost of granularity.
+
+**Dynamic import as a split point:**
+
+```javascript
+function onClick() {
+  import("./module")
+    .then((module) => module.default)
+    .catch((err) => {
+      console.log("Chunk loading failed")
+    })
+}
+```
+
+**Named dynamic-import chunk (magic comment):**
+
+```javascript
+import(
+  /* webpackChunkName: "app" */
+  "./app.jsx"
+).then((App) => {
+  // ...
+})
+```
+
+Use `webpackChunkName` when the review needs a stable, human-readable chunk name for budget tracking across builds — an unnamed dynamic-import chunk gets a content-hashed name that is harder to track budget deltas against over time.
+
+## Cross-bundler decision rule
+
+- Do not present a Rollup, Vite, or webpack chunking snippet as bundler-agnostic; the option names and defaults are not interchangeable, and copying a webpack `cacheGroups` shape into a Vite config (or vice versa) will not work.
+- Every chunking recommendation in a review must state which bundler and which major version it targets, resolved via Context7 for that specific project, not assumed from the most common current pattern in training data.

package/skills/frontend/bundle-budget-code-splitting-review/references/ci-enforcement-and-verification.md

@@ -0,0 +1,53 @@
+# CI Enforcement and Verification
+
+Use this reference for every review to specify the CI-enforced budget mechanism, the verification command, and the adversarial checklist before a size finding can be closed.
+
+## Non-negotiable: no finding closes without a CI-enforced budget
+
+A one-time manual fix — splitting a chunk, removing a dependency, adjusting `cacheGroups` — proves the bundle is smaller *today*. It proves nothing about tomorrow's dependency bump, an unreviewed import added six weeks from now, or a well-intentioned refactor that quietly reintroduces the same weight. Require one of the following, tied to the numeric budget established in [Budget methodology](budget-methodology.md), before marking any size finding resolved:
+
+- A `bundlesize`-style check (or equivalent size-limit tool) wired into CI that fails the build/PR when a named entry or chunk exceeds its budget.
+- A Lighthouse CI budget (`budgets.json` / `lighthouserc` budget assertions) that fails on `resource-summary` script/stylesheet byte-size thresholds.
+- A bundler-plugin size check (e.g., a Rollup/Vite/webpack plugin that asserts output size at build time) that fails the build rather than just reporting.
+
+If none of these exist in the project, state that as an explicit gap in the finding — do not let a review close as "fixed" when the only evidence is a single local `npm run build` byte count with no enforcement wired into CI.
+
+## Verification command
+
+State the exact command used to produce the before/after comparison, matching the project's actual tooling rather than assuming a generic one:
+
+- `npm run build -- --report` (or the project's equivalent analyzer-invoking build script) to regenerate the analyzer report.
+- For Vite projects, confirm whether `rollup-plugin-visualizer` (or an equivalent) is wired into the build config; if not present, state that as a prerequisite gap before a byte-level review can be evidence-backed rather than estimated.
+- For webpack projects, confirm `webpack-bundle-analyzer` (or the `--json` stats output piped into an equivalent tool) is available.
+- Always compare gzipped (or brotli, matching production `Content-Encoding`) sizes, not raw/parsed sizes, unless the budget was explicitly defined in a different compression form — see [Budget methodology](budget-methodology.md).
+
+## Adversarial checklist
+
+Before closing a bundle-size finding, answer these:
+
+- Is the budget tied to a percentile and a device/network class, or is it vague ("keep it small")? If vague, it is not a budget yet — fix that first.
+- Is the prescribed bundler chunking API confirmed against the installed major version via Context7, or is it a memorized snippet that might target a removed/deprecated API shape?
+- Does the proposed split reduce byte weight without increasing request count enough to net-negative the change? Was that comparison actually made, or only the byte number?
+- Is a CI-enforced budget check part of the deliverable, or only a one-time manual diff?
+- Was the ranking done by byte size alone, or also by main-thread execution cost? A large but rarely-executed module and a small but hot-path module do not carry equal INP risk.
+- If a dependency was flagged as "too heavy," was a lighter alternative actually identified with a size delta, or was "split it" offered as a substitute for that harder analysis?
+- If a dynamic `import()` specifier is built from any user-controlled input (route param, query string, feature flag value sourced externally), was that flagged as a code-injection risk, not filed only as a performance note?
+
+If any of these cannot be answered affirmatively, the finding is not ready to close — say so explicitly rather than presenting a partial analysis as complete.
+
+## When to push back
+
+Push back if the user asks for:
+
+- a one-time size fix with no request to add or verify a CI budget check — explain why that guarantees regression.
+- inlining a third-party script "to save a request" without acknowledging the CSP/SRI trade-off.
+- splitting every component in a route "to be safe," without a request-count comparison — that is not caution, it is trading one unverified assumption for another.
+- a chunking config copied from a different bundler or an unconfirmed version, because "it's probably still the same API" — that is exactly the failure mode this skill's Context7 protocol exists to prevent.
+
+Those are not shortcuts. They convert a measurable problem into an unmeasured one.
+
+## Handoff boundaries
+
+- If the root cause is unused exports inside an otherwise-necessary, correctly-split dependency: hand off to `tree-shaking-dead-code-review`.
+- If the user's starting complaint is a vague "it feels slow" with no analyzer report yet and JS weight has not been confirmed as the dominant contributor: hand off to `core-web-vitals-triage` first, then return here once bundle weight is confirmed as the cause.
+- If the fix under discussion is caching strategy for repeat visits rather than first-load byte weight: hand off to `service-worker-cache-strategy-review` (or the closest equivalent asset in scope) rather than stretching this skill's budget framing to cover caching.

package/skills/frontend/bundle-budget-code-splitting-review/references/code-splitting-boundaries.md

@@ -0,0 +1,46 @@
+# Code-Splitting Boundaries
+
+Use this reference when deciding where to add route- or component-level splitting, or when diagnosing a duplicated-dependency-across-chunks finding or an over-splitting regression.
+
+## What people get wrong
+
+The naive story is:
+
+> "More `import()` calls always make the bundle better."
+
+Wrong. Splitting trades parse/execute weight on one chunk for request-count and coordination overhead across chunks. Per web.dev's code-splitting guidance, the goal is to defer weight that is not needed for the current route/interaction — not to fragment the bundle for its own sake. Every additional chunk is an additional request the browser must schedule, and on a constrained connection or a cold cache, that overhead is real and can offset the byte savings the split was meant to deliver.
+
+## Classification per contributor
+
+For each large module identified in the analyzer report, classify it into exactly one path:
+
+1. **Needed on the critical path (keep, minimize).** The module is required to render the current route's above-the-fold content or its primary interaction. Do not split it away; instead look for a lighter alternative or confirm it is already tree-shaken (hand off to `tree-shaking-dead-code-review` if unused exports are suspected within an otherwise-necessary dependency).
+2. **Needed but deferrable (route/component-split candidate).** The module is required somewhere in the app but not on the current route's critical render/interaction path — e.g., a charting library only used on a `/reports` route, a modal's rich-text editor only needed after a user action. Split via dynamic `import()` at the route or component boundary where it is actually invoked.
+3. **Duplicated across chunks.** The same dependency (or a near-duplicate version) appears in the byte weight of more than one chunk. This is a chunk-grouping configuration defect, not an application-code defect — fix it via the bundler's vendor-chunk / `cacheGroups` / `codeSplitting.groups` configuration (see [Bundler chunking APIs](bundler-chunking-apis.md)), not by rewriting application imports.
+4. **Heavier than necessary for its purpose.** The dependency itself is oversized relative to what the app uses from it (e.g., importing a full date-utility library for one format call). Recommend a lighter alternative and state the size delta; do not default to "just split it" when the real fix is not depending on the heavy library at all.
+
+## Route-level vs. component-level splitting
+
+- **Route-level splitting** is the default first move: split at the router boundary so an entire route's code (including its route-specific dependencies) loads only when that route is navigated to. This is the highest-leverage split because it aligns with actual user navigation and typically yields one request per route transition, not per component.
+- **Component-level splitting** is for a specific heavy component *within* an already-loaded route that is not needed immediately — e.g., a modal, a below-the-fold widget, a rarely-used settings panel. Reach for this only after route-level splitting is exhausted; splitting every individual component inside an already-necessary route multiplies request count without changing what must load before the route is usable.
+- Do not recommend component-level splitting for something the user will interact with immediately on route entry — that just moves the same byte weight into a second network round trip with no benefit, and adds a loading-state flash that can itself become a CLS or perceived-jank complaint (hand off wording/attribution disagreements to `core-web-vitals-triage`).
+
+## Over-splitting: a real regression, not just a missed optimization
+
+Before endorsing any new split point, require a request-count comparison alongside the byte comparison:
+
+- If a split reduces the shared/critical-path bundle by N KB but adds M new chunks that are each fetched on the same route transition (e.g., several components all lazy-loaded on the same screen, each producing its own round trip), the net effect can be worse: more connection/scheduling overhead, more parse/compile invocations, and a longer time to fully interactive — even though the "critical path" number looks smaller in isolation.
+- HTTP/2+ multiplexing reduces but does not eliminate this cost: each chunk still has its own parse, compile, and module-registration cost on the main thread, which is the more INP-relevant number per `core-web-vitals-triage`'s execution-cost framing.
+- The correct test is: does total time-to-interactive (or the relevant INP-adjacent metric) improve, not just does the critical-path byte number shrink. State this comparison explicitly in the finding; do not accept a smaller entry-chunk number alone as proof of improvement.
+
+## Duplicated dependency across chunks — diagnosis path
+
+1. Confirm via the analyzer report (most bundle-analyzer tools flag this directly, e.g. webpack-bundle-analyzer's treemap showing the same module path under multiple chunk nodes) that the same module resolves into more than one output chunk.
+2. Check for version skew first — two different semver ranges of the same dependency resolving to two separate copies is an application-level (`package.json`/lockfile) defect, not a chunking-config defect; recommend a dependency dedupe/resolution fix, not a chunking change.
+3. If it is genuinely one version pulled into multiple chunks because multiple entry points or route chunks each import it, this is the textbook case for a shared vendor chunk (webpack `cacheGroups`) or an equivalent shared-group rule (Vite `codeSplitting.groups`) — see [Bundler chunking APIs](bundler-chunking-apis.md).
+
+## Non-negotiables
+
+- Do not recommend a component-level split for anything visible immediately on route entry.
+- Do not endorse a split without the request-count comparison alongside the byte comparison.
+- Do not treat a duplicated-dependency finding as an application-code problem before checking for version skew.

package/skills/frontend/core-web-vitals-triage/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: core-web-vitals-triage
+description: Decomposes LCP, INP, and CLS regressions into their documented sub-phases using lab and field evidence, and refuses to declare a metric fixed without a field-data or CI-budget verification path.
+allowed-tools: Read Grep Glob Bash(lighthouse:*) WebFetch
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-07-02"
+  category: operational
+---
+
+# Core Web Vitals Triage
+
+## Purpose
+
+Teams routinely shotgun-fix Core Web Vitals: compress an image, preload a font, and split a bundle in the same PR, then declare victory off one green Lighthouse run. That never isolates the actual cause, frequently doesn't move the field percentile Google's page-experience signal and real users actually experience, and burns engineering cycles on the wrong sub-phase. This skill decomposes an LCP, INP, or CLS regression into its documented sub-phases (per web.dev's LCP four-phase model, INP three-phase model, and the W3C Largest Contentful Paint / Event Timing specs), attributes each phase to a concrete verifiable cause, and refuses to close the loop without a field-data or CI-budget verification path — because a single lab run proves nothing about the field percentile that ranking and users actually see.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- diagnose a Core Web Vitals regression (LCP, INP, or CLS) reported by Lighthouse, PageSpeed Insights, CrUX, or Search Console's page-experience report,
+- explain why a page "feels slow" or "feels janky" in terms of a specific, verifiable rendering or interaction sub-phase,
+- reconcile a lab score change with (or without) a corresponding field percentile shift,
+- decide which downstream skill should implement a Core Web Vitals fix (bundle/code-splitting vs. caching vs. server/CDN).
+
+## When NOT to use
+
+- Pure server/infra latency tuning with no client-rendering component (TTFB-dominant LCP with no client-side contribution) — hand off to an infra/CDN-focused review; this skill identifies that TTFB is the dominant phase but does not own backend latency remediation.
+- Native mobile app performance — different metric model, not Core Web Vitals.
+- Implementing the fix. This skill diagnoses and specifies the fix, then hands off implementation-class changes to `bundle-budget-code-splitting-review` or `service-worker-cache-strategy-review` (or the closest equivalent asset in scope) — it does not write the fix code itself.
+
+## Context7 Documentation Protocol
+
+Framework rendering internals that affect LCP/INP attribution (image loading priority hints, hydration/streaming boundaries, transition scheduling) change between major versions, and memorized behavior goes stale fast. Before attributing a delay to a specific framework mechanism:
+
+1. Call `ToolSearch` with query `"context7"` (or `"select:mcp__Context7__resolve-library-id,mcp__Context7__query-docs"`) to load the Context7 tools if not already loaded this session.
+2. Call `mcp__Context7__resolve-library-id` for the framework in scope (e.g. Next.js, React, Vite) before making any claim about its current rendering/loading behavior.
+3. Call `mcp__Context7__query-docs` for the specific mechanism — e.g. "Image component priority/preload prop", "useTransition / startTransition scheduling", "manualChunks / codeSplitting build output" — before ruling on it. Do this per review; do not reuse a prior session's memory of framework internals.
+4. Known version-sensitive traps verified via Context7 as of this skill's `updated` date: Next.js deprecated the `<Image priority>` prop in Next.js 16 in favor of `preload` (same LCP-eager-load intent, new prop name — do not tell a Next.js 16+ user to add `priority` without checking their major version first). Vite deprecated the object form of `build.rollupOptions.output.manualChunks` in Vite 8+ in favor of `rolldownOptions.output.codeSplitting` — do not prescribe `manualChunks` config to a Vite 8+ project without verifying the installed version.
+5. web.dev is the primary source for Core Web Vitals *thresholds* and *phase definitions* and is not currently indexed in Context7; treat threshold/phase-boundary numbers pulled from `official_docs`/`WebFetch` as `documentation-based`, not `Context7-verified`, and say so explicitly.
+6. If Context7 is unavailable or returns no relevant match, fall back to `official_docs` / `references/*.md` and mark the claim `documentation-based (Context7 unavailable)` rather than presenting it as freshly verified.
+7. Never invent a framework prop, build-config option, or performance-entry field that no queried source confirms.
+
+## Lean operating rules
+
+- Classify the evidence tier before decomposing anything: field RUM data present (CrUX API or `web-vitals` library export) vs. lab-only (Lighthouse/PSI JSON). Cap the verdict ceiling at `lab evidence only` when field data is absent — never phrase a lab-only finding as a field-validated user-experience claim.
+- Decompose LCP into its four documented sub-phases (TTFB, resource-load delay, resource-load duration, render delay) per web.dev — never leave a finding at "LCP is high," always name the dominant phase.
+- Decompose INP into its three documented sub-phases (input delay, processing time, presentation delay) per web.dev — never attribute INP to generic "JS is slow" without naming which phase and which task/handler.
+- Decompose CLS by naming the specific shifting element and its trigger (late-loading web font, unsized image/embed, late-injected content, animation-triggered reflow) — a CLS score alone is not a diagnosis.
+- Distinguish lab CLS (bounded to a single automated load, per Lighthouse) from field CLS (session-long, includes user-triggered layout shifts within 500ms of input, per the field CLS definition) — do not generalize one to the other.
+- Attribute every phase to a concrete, verifiable artifact: a network-waterfall entry, a main-thread long-task entry, or a specific unsized DOM element. Never accept or emit "JS is slow" or "images are heavy" as a terminal diagnosis.
+- State the correct owning skill for any implementation-class fix (bundle/code-splitting for JS-weight causes, service-worker caching for repeat-visit causes) rather than attempting to specify the implementation here.
+- Never declare a metric "fixed" from a single lab run. State the CrUX 28-day rolling-window lag explicitly whenever recommending field-data confirmation.
+- Never recommend removing accessible loading-state semantics (`aria-live`, `role="status"`, visible focus indicators) as a CLS or INP fix — that trades a compliance/usability regression for a metric number.
+- Always account for device class: mobile field data (not desktop lab data) is what page-experience ranking and most real users actually see, per CrUX/web.dev methodology.
+
+## References
+
+Load these only when needed:
+
+- [LCP phase decomposition](references/lcp-phase-decomposition.md) — use when the regression or complaint is about page-load speed / the largest visible element painting late.
+- [INP phase decomposition](references/inp-phase-decomposition.md) — use when the regression or complaint is about interaction responsiveness / a page "feeling janky."
+- [CLS attribution](references/cls-attribution.md) — use when the regression or complaint is about visible layout jumping/shifting.
+- [Evidence tiers, verification, and handoff](references/evidence-tiers-and-handoff.md) — use for every triage to classify evidence tier, specify the re-verification path, and route implementation-class fixes to the correct owning skill.
+
+## Response minimum
+
+Return, at minimum:
+
+- per-metric verdict (LCP/INP/CLS as applicable) with its evidence tier (`field evidence` vs. `lab evidence only` vs. `documentation-based` vs. `inference`),
+- the sub-phase decomposition table for each metric in scope,
+- the root-cause attribution per phase, tied to a concrete artifact (waterfall entry, long-task entry, DOM element),
+- the minimal targeted fix per phase and which skill owns implementing it,
+- the exact re-verification command/tool and the field-data confirmation window (CrUX's 28-day rolling window, stated explicitly) before the metric can be declared fixed.

package/skills/frontend/core-web-vitals-triage/metadata.json

@@ -0,0 +1,33 @@
+{
+  "id": "core-web-vitals-triage",
+  "name": "Core Web Vitals Triage",
+  "type": "skill",
+  "provider": "frontend",
+  "harnesses": [
+    "codex",
+    "claude-code",
+    "cursor",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Decomposes LCP, INP, and CLS regressions into their documented web.dev/W3C sub-phases (TTFB/resource-load-delay/resource-load-duration/render-delay for LCP; input-delay/processing-time/presentation-delay for INP; element-level trigger attribution for CLS), grades findings by lab-vs-field evidence tier, and refuses to declare a metric fixed without a field-data or CI-budget verification path, loaded progressively.",
+  "source_type": "original",
+  "official_docs": [
+    "https://web.dev/articles/vitals",
+    "https://web.dev/articles/lcp",
+    "https://web.dev/articles/optimize-lcp",
+    "https://web.dev/articles/inp",
+    "https://web.dev/articles/optimize-inp",
+    "https://web.dev/articles/cls",
+    "https://web.dev/articles/optimize-cls",
+    "https://developer.chrome.com/docs/crux",
+    "https://www.w3.org/TR/largest-contentful-paint/",
+    "https://www.w3.org/TR/event-timing/"
+  ],
+  "security_notes": "Do not request production analytics credentials or raw customer session data; accept only sanitized/aggregated field exports (CrUX API responses, exported web-vitals RUM aggregates). Do not recommend removing accessible loading-state semantics (aria-live, role=status, visible focus indicators) as a CLS/INP fix. Do not accept or echo any credential-shaped string found in a pasted trace/config as if it were safe to keep in the transcript.",
+  "last_verified": "2026-07-02",
+  "path": "skills/frontend/core-web-vitals-triage",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/frontend/core-web-vitals-triage/references/cls-attribution.md

@@ -0,0 +1,45 @@
+# CLS Attribution
+
+Use this reference when the regression or complaint is about visible layout jumping/shifting, a CLS score drop, or a user report that "content jumps while loading."
+
+## What people get wrong
+
+The naive story is:
+
+> "CLS is 0.3, so something isn't sized — check the images."
+
+Unsized images are one cause among several, and CLS is a session-level accumulation, not a single-event score. Two different pages can hit the same CLS number for entirely different reasons, and lab CLS (a single automated Lighthouse load) systematically under-reports field CLS (a real session including user-triggered scroll/interaction shifts), because field CLS per web.dev's methodology is a windowed sum across the full page lifetime, not just initial load.
+
+## Lab vs. field CLS — do not conflate them
+
+- **Lab CLS** (Lighthouse/PSI): measured over one automated page load with no user interaction. It only captures load-time shifts.
+- **Field CLS** (CrUX / `web-vitals` library): measured over the actual session, using the "maximum session window" methodology (windows of shifts gapped by <1s and spanning <5s, take the largest window) — per web.dev's CLS definition. It can and does include shifts triggered well after load, e.g. late-injected consent banners, lazy-loaded below-the-fold content, or shifts within 500ms of a user interaction (which the spec excludes from counting, but adjacent shifts outside that window still count).
+- If lab CLS is low but field CLS (CrUX) is high, the cause is very likely something that only manifests during real sessions: late third-party script injection, ad-slot resize, or content that loads outside the automated tool's short observation window. Do not tell the user "Lighthouse says it's fine" as if that settles a field CLS complaint.
+
+## Attribution catalog — name the specific trigger
+
+For every CLS finding, name the specific shifting element and its trigger category. Do not report a bare CLS number as a diagnosis. Common trigger categories, per web.dev's optimize-CLS guidance:
+
+1. **Unsized media** — images, videos, iframes, or embeds rendered without explicit `width`/`height` attributes or a reserved `aspect-ratio`, so the browser doesn't know the box size until the resource loads. Fix: explicit intrinsic dimensions or CSS `aspect-ratio` on the container.
+2. **Web-font swap/FOIT-to-FOUT shift** — a fallback font renders at a different metric than the loaded webfont, causing reflow when the real font swaps in. Fix: `font-display` strategy tuned for the situation, and where supported, `size-adjust`/`ascent-override`/`descent-override` font-face descriptors to metric-match the fallback — verify current browser support before prescribing these descriptors as a guaranteed fix.
+3. **Late-injected content above existing content** — a banner, ad slot, cookie-consent widget, or async-loaded element inserted above content the user is already viewing, pushing everything below it down. Fix: reserve space for the element up front (a placeholder with the known/estimated final size) rather than letting it inject with zero reserved height.
+4. **Animation-triggered reflow** — CSS animations/transitions that animate layout-affecting properties (`width`, `height`, `top`, `left`, `margin`) instead of compositor-only properties (`transform`, `opacity`). Fix: rewrite the animation to use `transform`/`opacity` so it doesn't trigger layout at all.
+5. **Dynamically injected/removed DOM nodes tied to loading states** — a skeleton/spinner removed and replaced with real content at a different size. This is the category most likely to overlap with an accessibility loading-state pattern — see the non-negotiable below before touching it.
+
+## Non-negotiable: do not sacrifice accessible loading semantics for a CLS number
+
+A loading skeleton or spinner frequently carries `aria-live`, `role="status"`, or manages focus during a load transition. Do not recommend removing these attributes, collapsing the announcement, or eliminating visible focus indicators as a way to "simplify" the DOM and reduce shift count. If the loading-state element itself is the CLS trigger, fix it by reserving its layout space (matching the skeleton's box size to the final content's box size) — not by removing the accessibility semantics that make the loading state perceivable to assistive technology users. A metric win that produces a WCAG regression is not a fix; flag it as a conflict and specify the size-reserving fix instead.
+
+## Root-cause attribution — require an artifact, not an assertion
+
+Require one of:
+
+- A `LayoutShift` PerformanceObserver entry (per the W3C spec family CLS draws from) identifying the specific `sources` (nodes) and their `previousRect`/`currentRect`.
+- A Lighthouse/PSI "Avoid large layout shifts" audit entry naming the specific DOM node.
+- A DevTools Performance panel layout-shift region correlated to a specific paint frame and the element that moved.
+
+If none of these are available, the finding is capped at `inference` and must say so.
+
+## Verification target
+
+Re-run the trace and confirm the named element no longer appears in the layout-shift audit / `LayoutShift` entries. For field confirmation, see `references/evidence-tiers-and-handoff.md` — a lab-only CLS fix does not confirm the field CLS percentile improved, especially for triggers (late-injected content, session-long shifts) that lab tooling under-samples by design.

package/skills/frontend/core-web-vitals-triage/references/evidence-tiers-and-handoff.md

@@ -0,0 +1,57 @@
+# Evidence Tiers, Verification, and Handoff
+
+Use this reference for every triage, regardless of which metric (LCP/INP/CLS) is in scope, to classify evidence, specify the re-verification path, and route implementation-class fixes to the correct owning skill.
+
+## Evidence tiers — classify before decomposing anything
+
+Label every claim in the output with one of these tiers. Do not let a lab-only trace produce a field-level verdict.
+
+1. **Field evidence** — CrUX API p75 data for the specific origin/URL/device-class, or an aggregated export from a `web-vitals`-library RUM collector covering real user sessions. This is the only tier that can support a "this is what real users experience" verdict.
+2. **Lab evidence only** — a single Lighthouse/PSI run, a synthetic CI trace, or a local DevTools trace. Useful for sub-phase decomposition and root-cause attribution, but caps the verdict at "reproduced in a synthetic environment" — never phrase it as a confirmed real-user-experience claim.
+3. **Documentation-based** — a threshold, phase definition, or mechanism claim sourced from web.dev/W3C docs or Context7-queried framework docs, not from a trace the user provided. Correct for grounding definitions; not a substitute for evidence about this specific page.
+4. **Inference** — a plausible attribution without a cited artifact (waterfall entry, long-task entry, `LayoutShift`/`PerformanceEventTiming` entry). Must be labeled explicitly and should prompt a request for the missing artifact before the finding is treated as actionable.
+
+If field data is absent entirely, the ceiling for the whole triage is **lab evidence only** — recommend field instrumentation (the `web-vitals` JS library, or enabling/checking CrUX coverage for the origin) as a first-class next step, not an afterthought.
+
+## Device class matters — do not generalize desktop lab data to mobile field reality
+
+CrUX and the page-experience ranking signal are dominated by mobile field data for most origins. A desktop Lighthouse run that looks clean does not confirm the mobile field experience is clean, and the two frequently diverge (different CPU/network throttling profiles, different viewport-driven CLS triggers, different bundle-parse cost on slower mobile CPUs). Always state which device class a lab trace was captured against, and prefer mobile-throttled traces when field data specifically flags mobile.
+
+## CrUX's rolling window — the confirmation lag that must be disclosed
+
+CrUX reports a **28-day rolling window** of aggregated field data. This has two direct consequences for any "field-confirmed fixed" claim:
+
+- A fix deployed today will not be visible in CrUX's public dataset as a clean, isolated before/after split for up to 28 days, and even then the reported window blends pre- and post-fix days until the older data ages out.
+- Same-day or next-day CrUX checks after a deploy prove nothing about the field impact of that deploy. Do not let a user (or yourself) declare a metric "fixed" from a CrUX check taken within the rolling-window lag of the deploy.
+
+If the user wants faster confirmation than CrUX's window allows, the correct answer is same-origin RUM instrumentation (a `web-vitals`-library collector reporting to the user's own analytics pipeline), which can show a near-real-time before/after split — but that requires the user to already have or add that instrumentation; do not assume it exists.
+
+## Handoff table — this skill diagnoses, it does not implement
+
+| Dominant cause | Owning skill / next step |
+|---|---|
+| TTFB-dominant LCP | Server/CDN/infra latency review — out of this skill's cluster entirely |
+| JS bundle weight causing resource-load-delay, resource-load-duration, or INP input-delay/processing-time | `bundle-budget-code-splitting-review` (or the closest equivalent asset in the catalog for this provider) |
+| Repeat-visit caching / stale-resource causes | `service-worker-cache-strategy-review` (or the closest equivalent caching-strategy asset in the catalog) |
+| Single-element resource-hint fix (a missed preload/eager-load on the actual LCP element) | Specify directly in this skill's output; it's a targeted attribute change, not a build-pipeline change |
+| Framework-specific rendering/scheduling mechanism (transitions, image-loading props, hydration boundaries) | Verify via Context7 first (see SKILL.md protocol), then specify directly if it's a single-component change; hand off if it implies a broader architectural pattern change |
+| Accessibility-vs-metric conflict (loading-state semantics implicated in a CLS/INP finding) | Do not resolve by stripping accessibility semantics; specify the size/scheduling fix that preserves them, and flag the conflict explicitly |
+
+Do not reinvent bundle-splitting or caching-strategy guidance inside this skill — name the dominant cause, cite the artifact, and route to the owning skill so the fix is specified once, correctly, in the asset that owns it.
+
+## Adversarial checklist — answer before closing a triage
+
+- Is every sub-phase attribution backed by a cited waterfall/long-task/`LayoutShift`/`PerformanceEventTiming` entry, or is it asserted?
+- Is the evidence tier for the overall verdict correctly capped (lab-only claims never phrased as field-confirmed)?
+- Is the device class of every lab trace stated, and does it match the device class the field complaint (if any) refers to?
+- Is the CrUX 28-day lag disclosed if field re-confirmation is part of the recommended next step?
+- Is the fix routed to the correct owning skill instead of being reinvented here?
+- Does any proposed fix remove or weaken an accessible loading-state semantic? If so, it must be flagged as a conflict, not silently accepted.
+- Would declaring this metric "fixed" right now be true, or just true-in-the-lab?
+
+## Common failure modes to actively guard against
+
+- Shotgunning multiple simultaneous changes (image compression + font preload + code-splitting in one PR) so the actual causal phase is never isolated — insist on isolating the dominant phase before recommending a bundle of fixes, or at minimum flag that a bundled fix will make attribution of the eventual field-data improvement ambiguous.
+- Treating a single lab run, in either direction, as proof of anything about the field percentile.
+- Generalizing desktop lab data to a mobile field complaint, or vice versa.
+- Declaring victory the day after deploy based on a CrUX check that is still inside the 28-day blended window.

package/skills/frontend/core-web-vitals-triage/references/inp-phase-decomposition.md

@@ -0,0 +1,49 @@
+# INP Phase Decomposition
+
+Use this reference when the regression or complaint is about interaction responsiveness — a page "feels laggy," a PSI/CrUX INP score drop, or a Search Console page-experience INP warning.
+
+## What people get wrong
+
+The naive story is:
+
+> "INP is high, so the JavaScript bundle is too big — code-split it."
+
+Sometimes true, usually incomplete. INP measures the full latency of the interaction that produced the worst (or a high-percentile) responsiveness value in a session, per the W3C Event Timing spec. Bundle size affects one of three sub-phases; the other two are frequently the actual bottleneck and a bundle-size fix does nothing for them.
+
+## The three documented sub-phases
+
+Per web.dev's INP guidance, decompose the flagged interaction into:
+
+1. **Input delay** — from the user's physical input (click/tap/keypress) to the start of the event handler(s) processing it. Grown by: the main thread being busy with an unrelated task (a long task from a timer, a fetch-then-render cycle, a third-party script) when the input arrives.
+2. **Processing time** — the actual execution time of the event handler(s) triggered by the input, including any synchronous work chained inside it (state updates, synchronous re-renders, layout-triggering DOM reads/writes).
+3. **Presentation delay** — from processing completion to the next frame actually being presented, including style/layout/paint work and any work the browser defers to the next task (e.g. `requestAnimationFrame` callbacks).
+
+Every INP finding in this skill's output must name which of these three phases is dominant, tied to a specific long-task or event-handler entry — not just restate the total INP number.
+
+## Framework-specific attribution — verify via Context7, do not assume
+
+Resolve the framework via Context7 (see SKILL.md's Context7 Documentation Protocol) before attributing processing-time cost to a specific rendering mechanism. Confirmed via Context7 against `/reactjs/react.dev`:
+
+- React's `useTransition`/`startTransition` exists specifically to move non-urgent state updates off the synchronous, blocking render path so urgent updates (the actual click/keypress response) aren't queued behind them — per React's own framing, transitions "will be interrupted if more urgent updates like clicks or key presses come in." If processing-time is dominated by a large synchronous re-render triggered by an interaction, and part of that re-render is not required to satisfy the immediate visual feedback (e.g. re-rendering a large list after a filter change), that is the documented mechanism to reach for — verify the installed React major supports it (React 18+) before recommending it.
+- Do not claim a synchronous `setState` inside an event handler is inherently the INP cause without a long-task/processing-time artifact — React batches many such updates, and the actual cost may be in downstream layout/paint work (presentation delay), not the state update itself.
+- For any other framework in scope (Vue, Svelte, Angular), do not assume an analogous "transition" primitive exists or behaves the same way — query Context7 for that framework's current concurrency/scheduling primitives before recommending one.
+
+## Root-cause attribution — require an artifact, not an assertion
+
+For each phase you name as dominant, require one of:
+
+- A `PerformanceEventTiming` entry (per the W3C Event Timing spec: `processingStart`, `processingEnd`, `startTime`, `duration`) from field RUM instrumentation (the `web-vitals` library's INP attribution build, or equivalent).
+- A long-task entry (`PerformanceLongTaskTiming`) overlapping the input-delay or presentation-delay window, showing what else the main thread was doing.
+- A DevTools/Lighthouse trace showing the specific event handler's call stack and duration.
+
+If none of these are available, the finding is capped at `inference` and must say so.
+
+## Minimal targeted fix per phase (and who owns it)
+
+- **Input-delay-dominant** → identify and break up or defer the unrelated main-thread work that was running when input arrived (a competing long task, an eagerly-executing third-party script, an unbatched synchronous fetch handler). If the cause is JS parse/execution weight from the initial bundle, hand off to `bundle-budget-code-splitting-review`.
+- **Processing-time-dominant** → reduce the synchronous work inside the handler itself: defer non-urgent state updates (verify current framework primitive via Context7), memoize expensive derived computation, move genuinely heavy computation off the main thread (a Web Worker) rather than accepting it as unavoidable.
+- **Presentation-delay-dominant** → reduce layout/paint cost triggered by the update (avoid forced synchronous layout / layout thrashing, reduce the DOM subtree size affected by the update, check for expensive CSS selectors or filters/shadows recalculated on every frame).
+
+## Verification target
+
+Re-run field-representative interaction traces (Lighthouse's user-flow / timespan mode against the specific interaction, or a `web-vitals` INP attribution build in a staging RUM collector) and diff the three-phase breakdown against the pre-regression trace, not just the top-line INP number. See `references/evidence-tiers-and-handoff.md` for the field-data confirmation window before declaring the metric fixed.

package/skills/frontend/core-web-vitals-triage/references/lcp-phase-decomposition.md

@@ -0,0 +1,51 @@
+# LCP Phase Decomposition
+
+Use this reference when the regression or complaint is about page-load speed, a Lighthouse/PSI LCP score drop, or a CrUX LCP p75 shift.
+
+## What people get wrong
+
+The naive story is:
+
+> "LCP went from 2.3s to 3.8s, so the page got slower — compress the images."
+
+Wrong, or at least unverified. LCP is not one number produced by one cause. web.dev decomposes it into four sequential sub-phases, and the correct fix depends entirely on which phase grew. Compressing an image only helps if resource-load-duration is the dominant phase; if the regression is actually render-delay because the image is being lazy-loaded instead of eager-loaded, compression does nothing.
+
+## The four documented sub-phases
+
+Per web.dev's LCP guidance, decompose the LCP element's timeline into:
+
+1. **Time to First Byte (TTFB)** — from navigation start to the first byte of the document response. Server/CDN/redirect-chain territory, not a client-rendering fix.
+2. **Resource load delay** — from TTFB to when the browser starts loading the LCP resource (e.g. the hero image). Grown by: the resource being discovered late (not in the initial HTML, injected by JS, behind a render-blocking script), missing `fetchpriority="high"`/preload hints, or a redirect chain on the resource URL itself.
+3. **Resource load duration** — the time actually spent downloading the LCP resource. Grown by: resource size, missing compression/modern format, slow origin, lack of CDN, render-blocking requests competing for bandwidth/connections ahead of it.
+4. **Render delay** — from resource load complete to the element actually painting. Grown by: main-thread blocking (long tasks, large JS execution, web-font blocking text render), CSS/layout work queued ahead of the paint.
+
+Every LCP finding in this skill's output must name which of these four phases is dominant, with a waterfall-entry citation, not just restate the total LCP number.
+
+## Framework-specific attribution — verify via Context7, do not assume
+
+Do not attribute an LCP delay to a framework mechanism from memory. Resolve the framework via Context7 and query current docs first (see SKILL.md's Context7 Documentation Protocol). Known traps as of this skill's `updated` date, confirmed via Context7 against `/vercel/next.js`:
+
+- **Next.js `<Image>` eager-load prop is version-sensitive.** As of Next.js 16, the `priority` prop is deprecated in favor of `preload` (same intent — insert a `<link>` preload and skip lazy-loading for the LCP candidate — new prop name). Telling a Next.js 16+ user to add `priority={true}` is stale guidance; verify the installed Next.js major first, then recommend `preload` (16+) or `priority` (pre-16) accordingly. Either way: the LCP image must not be lazy-loaded by default (`loading="lazy"` is the `next/image` default) — that alone is a common render-delay root cause when the hero image regresses after an unrelated refactor accidentally drops the eager-load prop.
+- **Do not assume `fetchpriority="high"` alone fixes resource-load-delay** if the resource is still discovered late (e.g. only referenced inside a client-side-rendered component that itself waits on hydration). Preload hints only help resources the browser can discover early; a resource injected after JS execution still incurs discovery delay regardless of priority hints.
+- For non-Next.js stacks (Vite-based React/Vue/Svelte apps), verify current `vite-imagetools` / native `<img fetchpriority>` support against the installed Vite major via Context7 (`/vitejs/vite`) rather than assuming a plugin API that may have moved between majors.
+
+## Root-cause attribution — require an artifact, not an assertion
+
+For each phase you name as dominant, require one of:
+
+- A network-waterfall entry (from the Lighthouse/PSI JSON `resourceSummary`/`network-requests` audit, or a browser DevTools export) showing the specific request's start/end offsets.
+- A `LargestContentfulPaint` PerformanceObserver entry (`element`, `url`, `renderTime`, `loadTime`) per the W3C Largest Contentful Paint spec, if the user has instrumented field RUM.
+- For render-delay specifically: a long-task entry (`PerformanceLongTaskTiming`) overlapping the window between resource-load-complete and `renderTime`.
+
+If none of these are available, the finding is capped at `inference` and must say so — do not present a phase attribution as verified without a cited artifact.
+
+## Minimal targeted fix per phase (and who owns it)
+
+- **TTFB-dominant** → out of this skill's scope; hand off to server/CDN/infra review (redirect-chain removal, CDN edge caching, server response-time reduction). Do not prescribe a client-side fix for a TTFB problem.
+- **Resource-load-delay-dominant** → eager-load / preload the correct hint for the actual LCP element (verify current framework prop via Context7 first), remove render-blocking requests ahead of discovery, eliminate resource redirect chains. Implementation of a broader preload/resource-hint strategy across a route is `bundle-budget-code-splitting-review`'s territory if it touches build output; a single-element preload hint can be specified directly here.
+- **Resource-load-duration-dominant** → image/video compression, modern format (AVIF/WebP), responsive `sizes`/`srcset`, CDN/origin latency — hand off bundle-weight-class changes to `bundle-budget-code-splitting-review`.
+- **Render-delay-dominant** → identify and reduce the specific long task or web-font-blocking render ahead of the LCP paint; if the cause is JS bundle weight/parse time, hand off to `bundle-budget-code-splitting-review`.
+
+## Verification target
+
+Re-run the trace (Lighthouse CI or PSI API) against the same route/device-class combination and diff the four-phase breakdown, not just the top-line LCP number, against the pre-regression trace. See `references/evidence-tiers-and-handoff.md` for the field-data confirmation window before declaring the metric fixed.