@raishin/vanguard-frontier-agentic 3.0.2 → 3.1.1

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

@@ -0,0 +1,76 @@
+---
+name: bundle-budget-code-splitting-review
+description: Reviews JavaScript/CSS bundle composition against explicit numeric budgets, evaluates route- and component-level code-splitting boundaries, and requires a CI-enforced budget before endorsing any size fix as resolved.
+allowed-tools: Read Grep Glob Bash(npm run build:*) Bash(du:*)
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-07-02"
+  category: operational
+---
+
+# Bundle Budget & Code-Splitting Review
+
+## Purpose
+
+Teams routinely respond to "the bundle feels big" with an ad hoc `React.lazy()` here and a dynamic `import()` there, ship it, and call the finding closed once the build succeeds. That proves nothing: it does not show whether the total byte weight moved, whether the change reduced or inflated the request count, or whether the win survives the next dependency bump. This skill turns "bundle feels big" into a numeric, device/network-scoped budget tied to INP/TTI, ranks analyzer output by both byte weight and main-thread execution cost, classifies each contributor into a specific remediation path, and refuses to mark a size finding resolved without a CI-enforced budget check — a one-time manual fix without an enforced budget is a regression waiting to happen.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- reduce JavaScript or CSS bundle size,
+- review a bundle-analyzer report (webpack-bundle-analyzer, rollup-plugin-visualizer, or equivalent stats output),
+- set or enforce a performance budget for a route or shared entry,
+- decide where to add route-level or component-level code splitting,
+- assess the size impact of adding a new dependency before it merges.
+
+## When NOT to use
+
+- Pure image/media asset optimization — different budget class (bytes-per-image, format/compression), different tooling; not this skill's concern.
+- Server-side bundle or cold-start size for a serverless/edge function — different runtime, not the client-bundle budget this skill enforces.
+- Deciding whether a chunk's *contents* are dead code once it is correctly split — hand off to `tree-shaking-dead-code-review` for that specific question; a chunk can be correctly split and still be full of unused exports, which is a distinct defect from a splitting-boundary defect.
+- Diagnosing which Core Web Vitals sub-phase is regressing before a cause is known — hand off to `core-web-vitals-triage` first if the user only has a vague "it feels slow" complaint with no analyzer report yet; return here once JS weight is confirmed as the dominant contributor.
+
+## Context7 Documentation Protocol
+
+Bundler chunking APIs are version-sensitive and have changed shape recently — do not prescribe a config from memorized training data.
+
+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 bundler in scope (Vite, webpack, Rollup, esbuild, Rolldown) before prescribing any chunking configuration.
+3. Call `mcp__Context7__query-docs` for the specific mechanism — e.g. "manualChunks vs codeSplitting", "splitChunks cacheGroups", "dynamic import chunk naming" — before ruling on it. Do this per review; do not reuse a prior session's memory of bundler internals.
+4. Known version-sensitive trap verified via Context7 as of this skill's `updated` date: Vite 8 (Rolldown-powered) removes the object form of `build.rollupOptions.output.manualChunks` entirely and deprecates the function form; the documented replacement is `build.rolldownOptions.output.codeSplitting` with a `groups` array (`{ name, test }` entries). Do not hand a Vite 8+ project a `manualChunks: { vendor: [...] }` object-form snippet — it will not apply. For Vite <8, function-form `manualChunks(id) { ... }` is still valid but is itself deprecated and should be flagged as a forward-migration item, not endorsed as the long-term pattern.
+5. webpack's chunking surface (`optimization.splitChunks.cacheGroups`, dynamic `import()` with `webpackChunkName` magic comments) is comparatively stable across recent majors per Context7-grounded docs, but still confirm the installed webpack major before prescribing a specific `cacheGroups` shape, since defaults (`chunks: 'async'` vs `'all'`) affect which imports are eligible for splitting.
+6. If Context7 is unavailable or returns no relevant match for the installed bundler, fall back to `official_docs` and mark the claim `documentation-based (Context7 unavailable)` rather than presenting it as freshly verified.
+7. Never invent a bundler config key, CLI flag, or plugin option that no queried source confirms.
+
+## Lean operating rules
+
+- Establish the numeric budget before ranking anything. A budget with no device/network class and no percentile is not a budget — it is a guess. Refuse to close a finding against an undefined budget.
+- Rank analyzer contributors by both parsed/gzipped byte size and main-thread execution cost; these produce different orderings, and execution cost correlates more directly with INP than raw byte size does. Report both, do not collapse them into one number.
+- Classify every large module into exactly one path: needed on the critical path (keep, minimize), needed but deferrable (route/component-split candidate), duplicated across chunks (fix chunk-grouping config, not application code), or a heavier-than-necessary dependency (replace, or hand off to `tree-shaking-dead-code-review` if the issue is unused exports rather than the dependency itself).
+- Treat over-splitting as a real regression, not just under-splitting. Every new chunk is a new request; if the aggregate request-overhead cost (connection reuse aside, still parse/eval/scheduling cost) offsets the byte savings, the split is net-negative. Require the byte-vs-request-count comparison before endorsing a split.
+- Confirm the installed bundler major version via Context7 before prescribing `manualChunks`, `rolldownOptions.codeSplitting`, or `splitChunks` syntax — see Context7 Documentation Protocol. Do not assume a memorized API is still current.
+- Never accept "it built without errors" as evidence a split is beneficial. Require a before/after byte comparison from the analyzer output, gzipped or brotli as configured for production.
+- Flag any dynamic `import()` whose module specifier is built from unsanitized user input as a code-injection risk, not merely a performance nit — this is a security-relevant finding, not a style note.
+- Do not recommend inlining third-party scripts to "save a request" without naming the CSP/subresource-integrity trade-off of inlined vs. externally loaded, SRI-checkable code.
+- Require a CI-enforced budget (bundlesize, Lighthouse CI budget, or bundler-plugin size-limit check) as a condition of marking any size finding resolved. A manual one-time fix with no enforcement is not a fix, it is a snapshot.
+
+## References
+
+Load these only when needed:
+
+- [Budget methodology](references/budget-methodology.md) — use when the user has no existing budget, or an existing budget lacks a device/network class or percentile, and one must be established or corrected.
+- [Bundler chunking APIs](references/bundler-chunking-apis.md) — use when prescribing or reviewing Vite, webpack, or Rollup chunking configuration; contains the version-sensitive API grounding.
+- [Code-splitting boundaries](references/code-splitting-boundaries.md) — use when deciding where to add route- or component-level splitting, or when diagnosing duplicated-dependency-across-chunks and over-splitting.
+- [CI enforcement and verification](references/ci-enforcement-and-verification.md) — use for every review to specify the CI-enforced budget mechanism, the verification command, and the adversarial checklist before closing the finding.
+
+## Response minimum
+
+Return, at minimum:
+
+- the numeric budget in scope (bytes, compression form, device/network class, percentile), stated explicitly or flagged as missing,
+- the ranked contributor list with both byte size and main-thread execution-cost figures,
+- per-item classification (keep / split / replace / dead-code-handoff / chunk-grouping-fix) with the concrete config diff, version-confirmed against the installed bundler major,
+- the CI-enforced budget definition to add, not just a one-time manual fix,
+- the verification command (`npm run build -- --report` or the project's equivalent analyzer invocation) and the request-count check confirming the split did not net-negative the change.

package/skills/frontend/bundle-budget-code-splitting-review/metadata.json

@@ -0,0 +1,29 @@
+{
+  "id": "bundle-budget-code-splitting-review",
+  "name": "Bundle Budget & Code-Splitting Review",
+  "type": "skill",
+  "provider": "frontend",
+  "harnesses": [
+    "codex",
+    "claude-code",
+    "cursor",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Reviews JavaScript/CSS bundle composition against explicit numeric budgets, ranks analyzer contributors by byte weight and main-thread execution cost, evaluates route- and component-level code-splitting boundaries against version-confirmed bundler chunking APIs, and requires a CI-enforced budget before endorsing any size fix as resolved, loaded progressively.",
+  "source_type": "original",
+  "official_docs": [
+    "https://web.dev/articles/reduce-javascript-payloads-with-code-splitting",
+    "https://web.dev/articles/your-first-performance-budget",
+    "https://vite.dev/guide/build.html",
+    "https://webpack.js.org/guides/code-splitting/",
+    "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules/Dynamic_module_loading",
+    "https://webpack.js.org/plugins/split-chunks-plugin/"
+  ],
+  "security_notes": "Do not recommend inlining third-party scripts to save a request without disclosing the CSP/subresource-integrity trade-off of inlined vs. externally loaded, SRI-checkable code. Flag any dynamic import() of a module specifier built from unsanitized user input as a code-injection risk, not merely a performance concern. Do not accept or echo any credential-shaped string found in a pasted build config or analyzer report as if it were safe to keep in the transcript.",
+  "last_verified": "2026-07-02",
+  "path": "skills/frontend/bundle-budget-code-splitting-review",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

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

@@ -0,0 +1,36 @@
+# Budget Methodology
+
+Use this reference when the user has no existing performance budget, or an existing budget is missing a device/network class, a compression form, or a percentile — establish or correct it before ranking anything against it.
+
+## What people get wrong
+
+The common bad assumption is:
+
+> "Keep the bundle small" is a budget.
+
+It is not. A budget with no number is a slogan. A number with no device/network class and no percentile is a coin flip about whose experience it describes. Per web.dev's performance-budget guidance, a usable budget names:
+
+1. **the metric being bounded** — total JS/CSS transfer bytes, per-route transfer bytes, or a timing metric (TTI/INP) the byte budget is a proxy for,
+2. **the compression form** — gzip or brotli, matching what production actually serves; raw/uncompressed bytes overstate the number users pay for, and mixing forms across comparisons invalidates the comparison,
+3. **the device/network class** — a mid-tier mobile CPU on a throttled "good 4G" profile is a meaningfully different budget than an unthrottled desktop; web.dev's budget guidance frames budgets in terms of a target device class precisely because bundle-parse/execution cost scales with CPU, not just network time,
+4. **the percentile** — p75 is the conventional anchor (it is also the percentile Core Web Vitals field assessment uses), not the best-case or median session.
+
+## Establishing a budget when none exists
+
+1. Ask (or infer from existing CI config, `lighthouserc`, `bundlesize.config.json`, or a `size-limit` entry) whether a budget already exists in any form. Do not assume none exists just because this review wasn't asked to check.
+2. Anchor the budget to a route classification, not a single global number:
+   - **critical path / shared entry** — loaded on every route; tightest budget, since it blocks first render everywhere.
+   - **secondary route** — route-specific bundle loaded via code splitting; budget can be looser since it does not block other routes.
+   - **vendor chunk** — third-party dependency weight; budget separately from application code so a dependency bump is caught distinctly from an application-code regression.
+3. State the number in gzipped (or brotli, matching production) bytes, tied to p75 on the project's target device/network class. If the project has no stated target device/network class, default to a mid-tier mobile device on a throttled "good 4G" profile per web.dev's stated default budget context, and say explicitly that this default was assumed, not confirmed with the user.
+4. Tie the byte budget back to a timing outcome (TTI or INP) where possible — a byte number with no timing justification is arbitrary. State the reasoning explicitly (e.g., "X KB of parse/execute cost on the target device class corresponds to roughly Y ms of main-thread blocking, which risks the INP budget").
+
+## Correcting an existing but underspecified budget
+
+If a budget exists but is missing a device/network class or a percentile, do not silently adopt it as sufficient. State the gap explicitly as a finding, propose the missing dimension using the defaults above, and note that the corrected budget needs sign-off before being treated as CI-enforceable — see [CI enforcement and verification](ci-enforcement-and-verification.md).
+
+## Non-negotiables
+
+- Do not rank an analyzer report against a budget that has no stated compression form — a byte number with unstated compression is not comparable to anything.
+- Do not accept "under 250 KB" with no percentile or device class as a complete budget; treat it as a starting number that needs the missing dimensions filled in before enforcement.
+- Do not invent a budget number without grounding it in either the project's existing target (stated by the user, present in CI config) or web.dev's documented default budget context — state which one was used.

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.