@raishin/vanguard-frontier-agentic 3.0.1 → 3.1.0

package/skills/frontend/routing-navigation-review/references/focus-and-navigation-blocking.md

@@ -0,0 +1,65 @@
+# Focus Management and Navigation Blocking
+
+Use this reference only when reviewing focus/`aria-live` behavior on route transitions, or unsaved-changes navigation blocking. Load it during steps 6–7 of the review workflow.
+
+## What people get wrong
+
+The naive assumption is:
+
+> "React Router / Next.js handles focus on navigation automatically, like a real page load would."
+
+It does not, by default, in either framework. A client-side route transition in an SPA swaps DOM content without the browser's native full-page-navigation behavior (which resets focus to the document body and lets screen readers announce the new page title). If nothing in the application explicitly moves focus and announces the change, a screen reader user who navigates via a link ends up with focus still anchored to the link they just activated (now possibly removed from the DOM, or pointing at stale content) with no announcement that anything changed — a silent failure sighted users never notice because they can see the visual change.
+
+A second naive assumption:
+
+> "I added a confirm dialog with `window.confirm` in a `beforeunload` handler, so unsaved changes are protected everywhere."
+
+`beforeunload` only fires for hard navigations (reload, closing the tab, typing a new URL, following a link with a full page load). It does **not** fire for client-side SPA navigations triggered by the router — those need a router-level mechanism (e.g., React Router's `useBlocker`), which in turn has the opposite limitation: it does not cover hard reloads or cross-origin navigation. Neither mechanism alone is complete; a form-heavy route that cares about both needs both.
+
+## Officially grounded shape: focus management
+
+- Neither React Router nor Next.js ships automatic focus-to-heading-on-navigation behavior as a default, framework-level guarantee for arbitrary route trees. The established accessible-SPA pattern (consistent with the WAI-ARIA Authoring Practices Guide's page/route-change guidance) is: on route change, move focus to a stable, predictable target — commonly the page's `<h1>` (made programmatically focusable with `tabIndex={-1}`) or a `main` landmark — and pair it with an `aria-live="polite"` (or `assertive`, for urgent changes) region that announces the new page/section so screen reader users get an audible cue equivalent to what a full page load provides natively.
+- Look for this pattern implemented via a `useEffect` keyed on the route's location/pathname (React Router: `useLocation`; Next.js: `usePathname`) that calls `.focus()` on a ref, and a live region whose text content updates on the same trigger.
+
+## Design rules: focus management
+
+1. **Every route transition needs a defined focus target.** Absence of any focus-management code (no ref, no `.focus()` call, no live-region update keyed to navigation) is a HIGH finding (WCAG 2.4.3 Focus Order) — this is not cosmetic, it breaks the core navigation model for keyboard/screen-reader users.
+2. **The focus target should be stable and meaningful**, not an arbitrary or randomly-remaining-focused element. Flag a focus target that lands on something removed/re-rendered on every transition (causing focus loss anyway) or on an element with no semantic relationship to "the new page."
+3. **An `aria-live` announcement (or equivalent, e.g., a visually-hidden status element updated on navigation) should accompany the focus move** for the change to be announced, not just focusable — flag a repo that moves focus but never updates any live-region/status text as a WCAG 4.1.3 (Status Messages) gap, distinct from the 2.4.3 focus-order gap.
+4. **Do not assume a component library "handles this."** Verify by tracing the actual `useEffect`/ref/live-region code for the route(s) in scope; a UI kit's individual components (buttons, dialogs) having internal focus management does not imply the app's top-level router transitions do too.
+
+## Officially grounded shape: navigation blocking
+
+- React Router's documented mechanism for blocking in-SPA navigation is `useBlocker(shouldBlock)`, which returns a `Blocker` with `state` (`unblocked` | `blocked` | `proceeding`), and `proceed()`/`reset()` methods to let the confirmation UI resolve the block. It requires a data router (`createBrowserRouter` / framework mode) — it does not exist as a hook on the older `<BrowserRouter>` non-data-router API.
+- `useBlocker` explicitly does **not** intercept hard reloads, tab closes, or cross-origin navigations — those require a separate `beforeunload` handler. The two mechanisms are complementary, not interchangeable.
+- Next.js does not ship a first-party equivalent to `useBlocker` for App Router client-side transitions as a stable, documented primitive in the same way; verify current docs/Context7 before asserting a specific Next.js API exists, and if none is confirmed, flag the absence of any unsaved-changes protection as a finding rather than assuming a framework default covers it.
+
+## Design rules: navigation blocking
+
+1. **Form-heavy routes need unsaved-changes protection for SPA navigation**, hard reload/tab-close, or both, depending on what's realistic for the app. Absence entirely is a MEDIUM (escalate to HIGH for long/high-stakes forms) data-loss-risk finding.
+2. **If only `beforeunload` exists**, flag that in-app SPA navigation (clicking another nav link) is still unprotected — this is the more common real-world path a user takes to accidentally lose data, more so than closing the tab.
+3. **If only `useBlocker`/equivalent exists**, flag that hard reload/tab-close/cross-origin navigation is still unprotected, and confirm whether that gap is acceptable for the route's risk profile or needs a `beforeunload` handler added alongside it.
+4. **Verify the block condition is based on actual dirty-state tracking** (form value changed from initial), not a coarse "is this route a form" heuristic that blocks navigation even with no changes made — that's a usability regression in the opposite direction (blocking users who made no edits).
+
+## Adversarial checklist
+
+- For each route transition in scope, what element receives focus — did you trace it from an actual ref/`.focus()` call, or assume "it probably works"?
+- Is there an `aria-live` region (or equivalent) that updates on the same transition, or does focus move silently?
+- For each form-heavy route, does unsaved-changes protection exist at all? If so, does it cover SPA navigation, hard reload, or both — and is the gap (if any) acceptable?
+- Is the "unsaved changes" condition tied to real dirty-state, or would it block navigation even when nothing changed?
+
+## Safe verification targets
+
+- Grep for `useLocation`/`usePathname` combined with a `useEffect` and a `.focus()` call or ref assignment.
+- Grep for `aria-live` attributes and confirm their content updates on route change (not just present once, statically, with no dynamic text).
+- Grep for `useBlocker`, `beforeunload`, or equivalent on routes containing `<form>` elements or form-library state (e.g., react-hook-form's `formState.isDirty`).
+
+## When to push back
+
+Push back if the user says:
+
+- "the browser handles focus, we don't need to do anything" (true for hard navigations, false for SPA route transitions),
+- "we'll add focus management later, ship the route now" (this is a compliance gap the moment the route ships, not a deferred nice-to-have),
+- "`beforeunload` covers it" for a route whose primary navigation-away path is in-app link clicks, not tab closes.
+
+Those defer a defect users with assistive technology hit immediately, not an edge case.

package/skills/frontend/routing-navigation-review/references/server-enforcement-patterns.md

@@ -0,0 +1,90 @@
+# Server-Side Enforcement Patterns
+
+Use this reference only when auditing whether a "protected" route has real server-side enforcement versus client-side-only gating. Load it during step 3 of the review workflow.
+
+> Version note: React Router's `middleware` API and Next.js's Data Access Layer guidance are both relatively recent formalizations of patterns that existed informally before. Verify the installed major version before asserting these exact APIs exist; older codebases may implement equivalent checks through custom loader wrappers or `getServerSideProps`-era patterns.
+
+## What people get wrong
+
+The common bad assumption is:
+
+> "The route component checks `if (!user) redirect('/login')`, so it's protected."
+
+That check runs **inside the client-rendered tree**, after the route has already matched and after any component code (and often any data-fetching hooks) above the redirect has already begun executing. It also does nothing to stop a direct request for the route's data (an API call the component makes, or in Next.js, a Server Component that fetches before the redirect logic runs if the check is misplaced). A client-side redirect is a UX nicety for already-authenticated-but-wrong-state users; it is not an authorization boundary.
+
+## Officially grounded enforcement shape
+
+### React Router: loader (with middleware for forced execution)
+
+- The authoritative enforcement point is a `loader` that throws a `redirect()` (or throws a 401/403 response) when the request is unauthenticated/unauthorized. `redirect` thrown from a loader is the documented pattern for gating protected routes.
+- If middleware is used for cross-cutting auth logic, official React Router guidance notes that middleware alone does not run on every client-side navigation unless the route also has a `loader` — pairing an (even trivial, no-op) `loader` with the middleware forces the middleware to execute on every client-side transition into that route. A middleware with no paired loader is not a reliable enforcement point for client-side (SPA) navigations.
+- A route whose only "protection" is a check inside its `Component`/element (not its `loader`) is a client-side-only gate — flag it.
+
+Enforcement pointer to look for:
+
+```tsx
+export async function loader({ request }: Route.LoaderArgs) {
+  if (!isLoggedIn(request)) {
+    throw redirect("/login");
+  }
+  // ... fetch protected data only after the check
+}
+```
+
+### Next.js: Data Access Layer (not middleware alone)
+
+- Official Next.js guidance frames `middleware`/proxy-based auth checks as an **optimistic** check: it typically reads a session cookie's presence (not full validation) at the edge, primarily to redirect for UX purposes before a page even starts rendering.
+- The authoritative check belongs in a **Data Access Layer**: a server-only module (marked with `import 'server-only'` or equivalent) that every Server Component, Server Action, and Route Handler touching sensitive data calls into. This layer performs the real `auth()`/session validation, an authorization check (does this user own/have access to this specific resource — guarding against IDOR), and returns only a minimal safe DTO.
+- A route protected only by middleware, with no corresponding Data Access Layer check in the Server Component/Action/Route Handler that actually serves the data, is enforcement-incomplete — flag it as HIGH even if the middleware matcher is correctly scoped.
+- Server Actions in particular must re-check authentication and authorization inside the action itself (not rely on the fact that the triggering page was gated) — official production-checklist guidance calls this out explicitly, including checking resource ownership (e.g., `post.authorId !== session.user.id`) to prevent IDOR, not just "is logged in."
+
+Enforcement pointer to look for:
+
+```ts
+import 'server-only'
+import { auth } from '@/lib/auth'
+import { db } from '@/lib/db'
+
+export async function deletePost(postId: string) {
+  const session = await auth()
+  if (!session?.user) throw new Error('Unauthorized')
+
+  const post = await db.post.findUnique({ where: { id: postId } })
+  if (post.authorId !== session.user.id) throw new Error('Forbidden')
+
+  await db.post.delete({ where: { id: postId } })
+}
+```
+
+## Non-negotiable design rules
+
+1. **Every protected route needs a citable server-side enforcement pointer.** "The nav link is hidden" or "the component redirects" is not a pointer; a `loader` throw, a middleware-with-paired-loader, or a Data Access Layer call is.
+2. **Do not treat Next.js middleware as sufficient by itself.** It is a UX-redirect layer over an optimistic check. Require the Data Access Layer check too, and flag the gap if it's missing even when middleware looks airtight.
+3. **Check resource-level authorization, not just authentication.** "Is logged in" is necessary but not sufficient for routes/actions scoped to a specific resource (e.g., `/orders/:id`, `deletePost(postId)`) — verify an ownership/permission check exists, or the finding is an IDOR risk, not just a missing-auth risk.
+4. **Server Actions and Route Handlers must self-check.** Do not assume a Server Action inherits protection from the page that renders the form that triggers it — the official guidance requires the action to re-verify.
+5. **BFF/API-layer enforcement counts too.** If the frontend calls a backend-for-frontend or API layer that itself enforces authorization independent of the loader/DAL, that also satisfies the requirement — but verify it, don't assume "the API probably checks this."
+
+## High-risk assumptions to kill
+
+- "It's not in the nav, so users can't get there."
+- "The middleware matcher covers this path, so it's protected." (Next.js — middleware alone is optimistic.)
+- "The loader fetches the data, so of course it checks auth first." (Verify the check actually runs before the fetch, not after or not at all.)
+- "The Server Action is only called from the protected page's form, so it inherits protection." (It does not; actions are independently callable.)
+- "Checking `session?.user` is enough for a resource-scoped route." (Also check resource ownership/permission.)
+
+## Safe verification targets
+
+- Grep every route's `loader`/Server Component/Server Action/Route Handler for an auth check that occurs before any protected data fetch or mutation, and confirm it throws/redirects rather than just setting a flag a component might ignore.
+- For Next.js, grep for `middleware.ts`/`proxy.ts` and confirm whether a corresponding Data Access Layer (`server-only` import) exists and is actually called by the routes the middleware matches.
+- For React Router, confirm any auth `middleware` has a paired `loader` on the same route (or an ancestor layout route) to force execution on client-side navigations.
+
+## When to push back
+
+Push back if the user asks to:
+
+- ship a route as "protected" based solely on hiding a nav item or a component-level redirect,
+- rely on a Next.js middleware matcher alone as the complete authorization boundary,
+- skip resource-ownership checks because "the user is already logged in,"
+- skip re-checking auth inside a Server Action because "the calling page is already gated."
+
+Those are not shortcuts. They are authorization bypasses waiting for a direct URL, a replayed request, or a changed session state.

package/skills/frontend/routing-navigation-review/references/workflow-and-output.md

@@ -0,0 +1,68 @@
+# Review Workflow and Findings Contract
+
+Use this reference for the step-by-step review procedure, the route-tree mapping table, and the required output shape for a routing/navigation review.
+
+> Version note: React Router's route-module API (`loader`, `action`, `lazy`, `middleware`) and Next.js's App Router conventions (middleware/proxy, parallel/intercepting routes, `loading.tsx`) are version-sensitive. Verify the installed major version (`package.json`) before asserting exact API shape; React Router v5/v6-classic and Next.js Pages Router use materially different patterns than the current framework-mode/App Router guidance this skill is grounded in.
+
+## What people get wrong
+
+The naive assumption is:
+
+> "The route isn't in the nav menu / it redirects to `/login` in the component, so it's protected."
+
+That is incomplete in two distinct ways:
+
+1. A client-side redirect or conditional render still requires the route to match and the component tree to mount before the redirect fires. Nothing stops a user (or a script) from requesting the route's data directly, reading the JS bundle for that route, or racing the redirect. The only real gate is a check that runs **before** the sensitive work happens, on the server: a React Router `loader` that throws/redirects, or a Next.js Server Component/Server Action/Route Handler check.
+2. In Next.js specifically, teams often stop at a `middleware`/proxy check and call the route "protected." Official Next.js guidance is explicit that middleware-based checks are an *optimistic* pass (cookie presence, not full session validation) intended for UX redirects — the authoritative authorization check belongs in a server-only Data Access Layer close to the data source. A middleware-only implementation is not done; it is half-done.
+
+## Step-by-step workflow
+
+1. **Map the route tree.** Enumerate every route: path, layout nesting/parent chain, and whether it is an index route. Note which framework/router is in play (React Router framework mode vs. classic `<Routes>`; Next.js App Router vs. Pages Router) — the enforcement and code-splitting patterns differ by framework and by mode.
+2. **Classify protection level per route.** For each route, determine whether it is meant to be public or protected using the team's actual authorization model (ask if undocumented; do not assume). Do not infer protection level from the route's name or nav visibility.
+3. **Locate the server-side enforcement point for every protected route.** See `references/server-enforcement-patterns.md` for the exact patterns to look for in React Router (`loader`/middleware-with-loader) and Next.js (Data Access Layer). If none exists, this is the finding — do not continue to treat the route as protected for the rest of the review.
+4. **Inspect code-splitting boundaries.** For each lazily-loaded route, determine whether its component, loader, and action resolve via a parallel construct or a sequential `await` chain. See `references/code-splitting-and-url-state.md`.
+5. **Check URL-reconstructable state.** For each route with filters, pagination, tabs, or other view-affecting UI state, determine whether that state is represented in the URL (path segment or search params) or only in component/memory state. See `references/code-splitting-and-url-state.md`.
+6. **Trace focus management and status announcements.** For each route transition in scope, determine what receives focus after navigation and whether an `aria-live` region (or equivalent) announces the change. See `references/focus-and-navigation-blocking.md`.
+7. **Check navigation-blocking on form-heavy routes.** Determine whether unsaved-changes protection exists and whether its known SPA-only limits are accounted for. See `references/focus-and-navigation-blocking.md`.
+8. **Rank and report findings** per the output shape below.
+
+## Route-tree mapping table
+
+Produce this table before listing findings:
+
+| Path | Protection level | Enforcement pointer (file:line, or "none found") | Code-split boundary | Focus target on transition |
+|---|---|---|---|---|
+| `/dashboard` | protected | `app/dashboard/page.tsx` calls `getDashboardData()` DAL check, `lib/dal.ts:12` | route-level `lazy` | `<h1>` ref-focused in `layout.tsx:8` |
+| `/login` | public | n/a | eager | n/a |
+
+## Decision tree
+
+- Protected route has no server-side enforcement point (client-only redirect/hide, or Next.js middleware check with no matching Data Access Layer check) → **HIGH / block**. State exactly what exists (if anything) and why it is insufficient.
+- Protected route's only enforcement is a Next.js `middleware`/proxy check with no corresponding server-only check in the Server Component/Action/Route Handler that touches the data → **HIGH**. Middleware-only is not equivalent to a Data Access Layer check per current Next.js guidance.
+- Lazy route's component/loader/action are `await`-ed sequentially instead of via `Promise.all` or the framework's combined `lazy` loader → **MEDIUM**, waterfall regression; cite the measurable extra round trip.
+- View-critical state (filter/page/tab) exists only in component state with no URL representation → **MEDIUM/HIGH depending on user impact** (HIGH if the route is meant to be shareable/bookmarkable, e.g., a saved-search or report link).
+- Route transition has no defined focus target and no `aria-live` announcement → **HIGH** (WCAG 2.4.3 / 4.1.3), even if the app "looks fine" visually — this is an assistive-technology-only defect class.
+- Form-heavy route has no navigation-blocking for unsaved changes → **MEDIUM** data-loss risk; escalate to HIGH if the form represents non-trivial user input (long forms, financial/legal data entry).
+- `useBlocker` (or equivalent) is present but the route also needs hard-reload/tab-close protection and has none → **LOW/MEDIUM** note the gap; `useBlocker` explicitly does not cover hard reloads or cross-origin navigation.
+
+## Adversarial checklist
+
+Before closing a review with no HIGH findings, confirm:
+
+- For every route you called "protected," did you find and cite the actual server-side enforcement pointer, or did you accept a nav-hiding/component-redirect as sufficient?
+- For every Next.js protected route, did you check for a Data Access Layer check in addition to (or instead of) middleware, per current official guidance?
+- Did you verify lazy-loaded routes resolve component/loader/action in parallel, not just that `lazy` is used at all?
+- Did you check every route with filter/pagination/tab UI for URL representation, not just the ones an issue report already flagged?
+- Did you trace focus behavior from source (refs, `useEffect` on location change, `aria-live` regions) rather than assuming a framework "handles it automatically"?
+- If you found zero HIGH findings, is that because none exist, or because you didn't trace enforcement/focus/URL-state far enough?
+
+## Output shape
+
+Every review response must include:
+
+1. **Scope** — routes and files reviewed, framework/router and major version noted.
+2. **Route-tree mapping table** — as specified above.
+3. **Findings** — ranked HIGH → MEDIUM → LOW, each with `file:line`, the category (enforcement gap / waterfall / URL-state / focus-management / navigation-blocking), and a concrete fix sketch.
+4. **Evidence level** per finding: `repo evidence`, `documentation-based`, or `inference`.
+5. **Verdict** — approve / approve-with-notes / block. Any protected route with no server-side enforcement point is an automatic block.
+6. **Open questions** — anything the review could not verify (unconfirmed framework version, runtime focus behavior not simulated, ambiguous authorization model).

package/skills/frontend/service-worker-cache-strategy-review/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: service-worker-cache-strategy-review
+description: Reviews service-worker route-matching and caching-strategy choices (precache vs. cache-first vs. network-first vs. stale-while-revalidate) against request type and security sensitivity, rejecting uniform blanket strategies and flagging authenticated/PII responses cached in the Cache API.
+allowed-tools: Read Grep Glob
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-07-02"
+  category: security
+---
+
+# Service Worker Cache Strategy Review
+
+## Purpose
+
+A service worker is a persistent, cross-session, JS-controlled cache layer that sits in front of every network request the browser makes for a scope. Unlike HTTP caching, it is not opt-in per response — once a route is matched, the developer's strategy code decides freshness and disclosure, not `Cache-Control`. The common failure mode is copy-pasting one strategy (usually `CacheFirst`, straight from a tutorial) across navigation, API, and asset routes without differentiating by freshness need or security sensitivity. This skill performs the per-route-class review that catches both the stale-content incidents that uniform cache-first causes on navigation/API routes, and the security incidents that happen when authenticated or PII-bearing responses land in a persistent Cache API store that Workbox strategies do not automatically protect.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- review a service-worker file or Workbox config (`generateSW`/`injectManifest`) for caching-strategy correctness,
+- debug reports of stale content after deploy, broken offline pages, or unexpectedly cached dynamic/API data,
+- choose or validate a caching strategy per route class (navigation, API, static asset) before shipping,
+- audit `scope` / `Service-Worker-Allowed` coverage and cache-versioning/cleanup behavior.
+
+## When not to use
+
+- Manifest/installability review with no caching-behavior question — use `pwa-offline-readiness-review` instead.
+- General HTTP `Cache-Control`/`ETag` header review with no service worker involved — that is standard HTTP caching, a narrower and materially different concern than programmatic Cache API control.
+
+## Context7 Documentation Protocol
+
+Workbox strategy internals and Vite-PWA config surface change between major versions — never assert runtime semantics (what bypasses HTTP headers, what revalidates, what the default `expiration` behavior is) from memory.
+
+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 in this session.
+2. Resolve `/googlechrome/workbox` for the strategy implementation in question (`PrecacheStrategy`, `CacheFirst`, `NetworkFirst`, `StaleWhileRevalidate`, `NetworkOnly`, `ExpirationPlugin`, `cleanupOutdatedCaches`).
+3. Resolve `/websites/vite-pwa-org_netlify_app` (or the closest match) when the project uses Vite PWA's `generateSW`/`injectManifest` config surface, `runtimeCaching`, `skipWaiting`/`clientsClaim`, or custom `injectManifest` service-worker source.
+4. Query for the exact behavior before ruling — e.g. "does PrecacheStrategy revalidate against Cache-Control", "NetworkFirst networkTimeoutSeconds fallback behavior", "ExpirationPlugin maxAgeSeconds vs maxEntries eviction order" — per review, not once from a prior session.
+5. A confirmed, version-specific fact from Context7 (e.g. `precacheAndRoute` serves via `PrecacheStrategy`, which reads from the Cache API and returns immediately on a hit, completely bypassing HTTP `Cache-Control` since no network round-trip occurs) is materially different from the general folk claim "precache is cache-first" — cite the specific mechanism, not the folk version.
+6. If Context7 is unavailable or has no relevant match, fall back to `official_docs` / `references/workbox-strategy-semantics.md`, and mark the claim `documentation-based (Context7 unavailable)` rather than presenting it as freshly verified.
+7. Never invent a Workbox option, plugin, or config key that no queried source confirms.
+
+## Lean operating rules
+
+- Classify every matched route into navigation/HTML, API/data (split further: read vs. write, public vs. authenticated), and static asset before judging any single strategy — a strategy is only correct or incorrect relative to its route class.
+- Treat `PrecacheStrategy`/precache-and-route as a distinct mechanism from runtime `CacheFirst` — precache serves from the Cache API with no revalidation and no HTTP `Cache-Control` involvement at all; do not describe the two interchangeably.
+- Cache API only stores GET responses by spec — if a review encounters a manual `cache.put()` on a non-GET request or response, treat that as a code smell requiring explanation, not a strategy question.
+- Any response containing `Set-Cookie`, an echoed `Authorization` value, or clearly PII/payment-bearing JSON is a hard block on caching, regardless of the performance justification offered — recommend `NetworkOnly` or explicit route exclusion instead.
+- Never accept "it's cached, so it's fast, so it's fine" as sufficient for navigation/HTML routes — blind cache-first strands users on a stale app shell after every deploy; require `StaleWhileRevalidate` or `NetworkFirst` there instead.
+- Flag `cache.put()` on an opaque, cross-origin `no-cors` response — the caller cannot inspect status or headers on an opaque response, so a poisoned or error response can be cached and served indefinitely with no visibility.
+- Verify `scope` (registration time) and `Service-Worker-Allowed` (response header, only needed when the script itself sits outside the desired scope) match the intended route coverage exactly — broader-than-needed scope expands blast radius for every finding above.
+- Verify a versioned cache-name scheme plus an `activate`-event cleanup step (or Workbox's `cleanupOutdatedCaches`) exists, and that `skipWaiting`/`clients.claim()` or a deliberate user-prompted update flow gets fixes to users in bounded time — otherwise caches grow unbounded and rollbacks/forward-fixes never land.
+- Query current Workbox/Vite-PWA docs (see Context7 Documentation Protocol) for the specific strategy/option in question before ruling; runtime semantics are version-sensitive and have changed across Workbox major versions.
+- Label every claim as `live evidence`, `spec-cited`, `documentation-based`, or `inference` so the reviewer knows what has actually been verified vs. reasoned about.
+
+## References
+
+Load these only when needed:
+
+- [Workbox strategy semantics](references/workbox-strategy-semantics.md) — use when confirming the exact runtime behavior of a specific strategy (precache vs. `CacheFirst` vs. `NetworkFirst` vs. `StaleWhileRevalidate` vs. `NetworkOnly`), expiration/cleanup mechanics, or Vite-PWA `generateSW`/`injectManifest` wiring.
+- [Route classification and strategy matrix](references/route-classification-matrix.md) — use when mapping a concrete route inventory to a strategy per class and justifying the mapping.
+- [Cache security and scope audit](references/cache-security-and-scope-audit.md) — use before endorsing any strategy change, when reviewing authenticated/PII route handling, opaque-response caching, or `scope`/`Service-Worker-Allowed`/cache-versioning coverage.
+
+## Response minimum
+
+Return, at minimum:
+
+- the route classification (navigation / API read-public / API read-authenticated / API write / static asset) for every matched route pattern in scope,
+- per-class strategy verdict with the Workbox-version-confirmed runtime semantics behind it,
+- security flags (blocker severity) for any authenticated/PII response cached, any opaque cross-origin `cache.put()`, or any scope broader than required,
+- cache-versioning and `activate`-cleanup audit result, including whether `skipWaiting`/`clients.claim()` or an equivalent update path exists,
+- verification steps (DevTools Application > Cache Storage inspection of actual cached entries, offline-throttle test) and a rollback note (cache-name version bump plan).

package/skills/frontend/service-worker-cache-strategy-review/metadata.json

@@ -0,0 +1,29 @@
+{
+  "id": "service-worker-cache-strategy-review",
+  "name": "Service Worker Cache Strategy Review",
+  "type": "skill",
+  "provider": "frontend",
+  "harnesses": [
+    "claude-code",
+    "cursor",
+    "codex",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Reviews service-worker route-matching and caching-strategy choices (precache vs. cache-first vs. network-first vs. stale-while-revalidate) against request type and security sensitivity, rejecting uniform blanket strategies and flagging authenticated/PII responses cached in the Cache API.",
+  "source_type": "original",
+  "official_docs": [
+    "https://developer.chrome.com/docs/workbox/",
+    "https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API",
+    "https://developer.mozilla.org/en-US/docs/Web/API/Cache",
+    "https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Vary",
+    "https://web.dev/articles/service-worker-caching-and-http-caching",
+    "https://owasp.org/www-community/attacks/Cache_Poisoning"
+  ],
+  "security_notes": "Hard-block caching of any response carrying Set-Cookie, an echoed Authorization value, or clearly PII/payment-bearing JSON without explicit, reviewed justification. Hard-block a service-worker scope broader than the routes it is meant to control unless justified. Flag cache.put() calls on opaque (no-cors) cross-origin responses as an unreviewable-content risk per OWASP cache-poisoning concerns. Do not paste real user session data, cookies, or authenticated response bodies into review examples.",
+  "last_verified": "2026-07-02",
+  "path": "skills/frontend/service-worker-cache-strategy-review",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/frontend/service-worker-cache-strategy-review/references/cache-security-and-scope-audit.md

@@ -0,0 +1,48 @@
+# Cache Security and Scope Audit
+
+Use this reference before endorsing any caching-strategy addition or change, when reviewing authenticated/PII route handling, opaque cross-origin response caching, or `scope`/`Service-Worker-Allowed`/cache-versioning coverage. This is the hard-gate section of the skill — findings here are blockers, not style notes.
+
+## What people get wrong
+
+The common bad assumption is:
+
+> "It worked fine when I tested it, so the caching is safe."
+
+Wrong, and dangerously so for shared/multi-account devices. A service worker's Cache API store is per-origin and persists across navigations and sessions — it has no built-in concept of "which user" a cached response belongs to. If an authenticated route (`/api/user`, `/api/account`, `/api/orders/:id`) is cached with any strategy that reads before checking identity, a single-session manual test will look correct while silently setting up cross-user data disclosure the moment a second user logs in on the same device without a full cache purge. This is not a hypothetical: it is the single most severe class of finding this skill exists to catch, and it is invisible to functional QA that only ever tests with one account.
+
+## Non-negotiables
+
+- Do not endorse caching a response containing `Set-Cookie`, an echoed `Authorization` header/token value, or clearly PII/payment-bearing JSON, under any performance justification. The correct strategy for such a route is `NetworkOnly` or explicit exclusion from every `registerRoute`/`urlPattern` matcher — not a "short TTL" compromise.
+- Do not endorse a `scope` broader than the routes the service worker is meant to control. `scope` is set at `register()` time (`navigator.serviceWorker.register(url, { scope })`) and defines the maximum set of URLs the worker can intercept; a worker registered at `/` when it only needs to control `/app/` unnecessarily expands the blast radius of every other finding in this file.
+- `Service-Worker-Allowed` is a response header needed only when the service-worker *script* itself is served from a path outside the desired scope (e.g., script at `/sw.js` needs to control `/app/`, requiring the server to send `Service-Worker-Allowed: /app/` on the script response). Confirm it is present and no broader than necessary whenever the script path and intended scope diverge.
+- Flag `cache.put()` on an opaque (`no-cors`, cross-origin) response as an unreviewable-content risk per OWASP cache-poisoning guidance applied to Cache API misuse: an opaque response's status and headers cannot be inspected by the calling JS, so a `404`, an error page, or a compromised/poisoned upstream response can be cached and served as if it were a valid `200` indefinitely, with zero visibility from the caching code.
+- Do not accept "we'll purge the cache manually if this becomes a problem" as a mitigation for authenticated-data caching. There is no reliable trigger for "manually" here — the fix is not caching it in the first place.
+
+## Minimal safe audit flow
+
+1. Enumerate every route matcher and cross-reference against `route-classification-matrix.md` to identify which, if any, are classified authenticated/PII.
+2. For every authenticated/PII route, confirm the applied strategy is `NetworkOnly` or that the route is excluded from all matchers (i.e., falls through to the browser's normal network path with no service-worker interception at all).
+3. Open DevTools → Application → Cache Storage (or run the equivalent inspection command in an automated check) and manually inspect actual cached entries — do not trust config intent alone. Look for any entry whose URL matches an authenticated/PII route class, and for any response body containing session tokens, emails, names, or account identifiers that shouldn't be persisted client-side.
+4. Confirm `scope` at registration matches the intended coverage, and `Service-Worker-Allowed` (if applicable) is no broader.
+5. Confirm a versioned cache-name scheme exists (e.g., `app-cache-v3`) and that `activate` either calls `cleanupOutdatedCaches()` (Workbox precaching) or manually deletes cache keys not in the current manifest/version — an unbounded, unversioned cache cannot be reliably rolled back or purged.
+6. Confirm any `cache.put()` call on a cross-origin request is not operating on an opaque response, or is explicitly justified and reviewed if it must be (e.g., a trusted, pinned third-party origin with documented risk acceptance).
+
+## Adversarial checklist
+
+Before signing off on any caching-strategy change, answer these:
+
+- Is every authenticated/PII route verified excluded by inspecting actual cached entries in DevTools, not just by reading the strategy config?
+- If this device is shared or a second user logs in without a full logout/cache-clear, can any previously cached response leak across accounts?
+- Does `scope` match only what this worker needs to control, verified against the actual `register()` call, not assumed from the script's file location?
+- Is there a versioned cache-name and `activate`-time cleanup path, verified by checking that an old-version cache key actually gets deleted after a version bump — not just present in code but unexercised?
+- Is every `cache.put()` on a cross-origin request either non-opaque (`cors` mode with an inspectable response) or explicitly justified?
+
+If any of these cannot be answered from direct evidence (config read, DevTools inspection, or explicit user-provided confirmation), the finding is a residual risk, not a pass.
+
+## When to push back
+
+Push back if the user asks for:
+
+- caching an authenticated API response "just for this one screen" to make it feel faster — the risk is identical regardless of scope of use,
+- a broader `scope` than the app actually needs "in case we add more routes later" — expand scope when the need is real, not speculatively,
+- skipping the DevTools cache-entry inspection step because "the config looks right" — config intent and actual cached content diverge often enough (matcher bugs, stale test data, prior strategy still in a live cache) that this step is not optional.

package/skills/frontend/service-worker-cache-strategy-review/references/route-classification-matrix.md

@@ -0,0 +1,47 @@
+# Route Classification and Strategy Matrix
+
+Use this reference when mapping a concrete route inventory (the actual `registerRoute`/`urlPattern` matchers in the service worker or Workbox config) to a caching strategy per class, and when a review needs to justify why one class gets a different strategy than another.
+
+## What people get wrong
+
+The common bad assumption is:
+
+> "We picked a caching strategy for the service worker" — as if one strategy applies to the whole app.
+
+Wrong. A service worker's `fetch` handler intercepts every request type in its scope — HTML navigations, API calls, images, fonts, scripts — and each has a different freshness contract and a different security profile. A single copy-pasted strategy (almost always `CacheFirst`, lifted from a tutorial about caching fonts) applied uniformly is the single most common defect this skill exists to catch. It is not "faster" across the board; it is wrong for at least two of the four classes below in nearly every real app.
+
+## Non-negotiable design rule: classify before you judge
+
+Before ruling on any single `registerRoute`/`runtimeCaching` entry, classify every matched route into one of these buckets. A strategy is only correct or incorrect *relative to its class* — there is no universally "best" strategy.
+
+## Route class → strategy matrix
+
+| Route class | Example | Correct default strategy | Why |
+|---|---|---|---|
+| Static asset, content-hashed filename | `/assets/app.a1b2c3.js`, webfonts | Precache (`precacheAndRoute`) or `CacheFirst` with long `maxAgeSeconds` | Immutable — a content change produces a new URL, so serving a stale cached copy under the old URL is impossible by construction. |
+| Static asset, NOT content-hashed | `/logo.png`, `/favicon.ico` | `StaleWhileRevalidate` with `ExpirationPlugin` | Can change without a URL change; needs periodic revalidation, but instant-from-cache is still safe since content is non-sensitive. |
+| Navigation / HTML (app shell, document requests) | `/`, `/dashboard` (document destination) | `StaleWhileRevalidate` or `NetworkFirst` (short `networkTimeoutSeconds`) — never blind `CacheFirst` | Blind cache-first strands users on a stale app shell after every deploy, since the HTML entry point is how new asset references reach the client at all. |
+| API GET, public/non-sensitive | `/api/public-catalog` | `StaleWhileRevalidate` or `NetworkFirst` with short TTL (`ExpirationPlugin.maxAgeSeconds`) | Needs freshness bounded by business tolerance for staleness; non-sensitive, so caching itself is not a security concern — only staleness is. |
+| API GET, authenticated/PII-bearing | `/api/user`, `/api/account`, `/api/orders/:id` | `NetworkOnly`, or explicit exclusion from any `registerRoute` match entirely | Hard security block — see `cache-security-and-scope-audit.md`. No performance justification overrides this. |
+| API mutation (POST/PUT/PATCH/DELETE) | any write endpoint | Not cacheable by Cache API spec (GET-only); verify no workaround exists | If a manual `cache.put()` appears on a mutation response, that is a code smell requiring explanation on its own, independent of strategy choice. |
+| Cross-origin, third-party, `no-cors` | third-party widgets, uncontrolled CDNs | Avoid `cache.put()` on the resulting opaque response, or scope tightly with clear justification | Opaque responses cannot be inspected for status/headers — see `cache-security-and-scope-audit.md`. |
+
+## Verification targets
+
+- Enumerate every `registerRoute`/`urlPattern` matcher in the file/config under review and assign it exactly one row from the matrix above — an unassignable route (matches nothing cleanly) is itself a finding: the matcher is probably too broad.
+- For each matcher, confirm the *matcher itself* is scoped correctly — a regex like `/^\/api\//` bundling public and authenticated endpoints under one strategy is a classification bug even before the strategy choice is evaluated.
+- Confirm no single strategy declaration (e.g., one `CacheFirst` block) is reused across more than one route class without an explicit justification for why that class's freshness/security needs happen to coincide.
+
+## High-risk assumptions to kill
+
+- "One strategy for the whole app is simpler to maintain" — simplicity here trades directly against both stale-deploy incidents and cross-user data leakage; the per-class matrix is the actual minimum safe design, not an optional refinement.
+- "It's a GET request, so it's safe to cache" — GET-only is a Cache API constraint, not a security guarantee; `/api/user` is a GET and is exactly the kind of route that must never be cache-first.
+- "The tutorial cached fonts with CacheFirst, so CacheFirst is the safe default" — `CacheFirst` is only safe for the specific class (immutable/rarely-changing, non-sensitive) the tutorial was written for.
+
+## When to push back
+
+Push back if the user asks to:
+
+- apply one strategy across the whole `fetch` handler "to keep the config simple,"
+- cache an authenticated or account-scoped API route with any strategy other than `NetworkOnly`/exclusion, regardless of the performance rationale offered,
+- skip per-route classification because "it's basically all API calls" — read/write and public/authenticated are not the same bucket even when the URL prefix is shared.

package/skills/frontend/service-worker-cache-strategy-review/references/workbox-strategy-semantics.md

@@ -0,0 +1,44 @@
+# Workbox Strategy Semantics
+
+Use this reference when a review needs to confirm the exact runtime behavior of a caching strategy — precache vs. `CacheFirst` vs. `NetworkFirst` vs. `StaleWhileRevalidate` vs. `NetworkOnly` — or the Vite-PWA `generateSW`/`injectManifest` config surface that produces it, before ruling on whether it matches a route's freshness/security needs.
+
+## What people get wrong
+
+The common bad assumption is:
+
+> "Precaching is just cache-first for build assets."
+
+Incomplete, and dangerous when carried into a security review. Per Workbox v7 source (`workbox-precaching/src/PrecacheStrategy.ts`, confirmed via Context7 against `/googlechrome/workbox`), `precacheAndRoute()` registers a `PrecacheRoute` whose `_handle` calls `handler.cacheMatch(request)` and **returns immediately on a hit — no network request, no revalidation, no HTTP involvement at all**. That is not "cache-first that also checks freshness sometimes" — it is a pure Cache API read with zero interaction with `Cache-Control`, `ETag`, or `Vary`. A runtime `CacheFirst` strategy is a different, separate mechanism: it also serves from cache on a hit, but falls through to a real network fetch (and populates the cache) on a miss. Treating the two as interchangeable in a finding misattributes which HTTP headers matter and which don't.
+
+> Version note: Workbox internals are version-sensitive. Confirm exact behavior against the installed Workbox major version via Context7 (`/googlechrome/workbox`) or the live `https://developer.chrome.com/docs/workbox/` docs before ruling — do not cite this file's summaries as the final word for an unverified version.
+
+## Officially grounded strategy shape
+
+Per Workbox docs/source (Context7-confirmed):
+
+- **Precache (`precacheAndRoute`)** — build-time-known, content-hashed assets. Served from Cache API with no revalidation, no HTTP cache-control involvement. Correct only for immutable, versioned assets where the precache manifest itself is the freshness mechanism (a new manifest = new cache entries).
+- **`CacheFirst` (recipe/strategy)** — checks cache; on hit, returns immediately (no revalidation on hit, same as precache once cached); on miss, fetches network and populates cache. Per the Workbox Recipes README, this is "ideal for assets that rarely change, such as fonts or images" — not for anything that can change without a URL change.
+- **`StaleWhileRevalidate`** — serves the cached response immediately if present, then makes a network request in the background to update the cache for the *next* request. Balances performance and freshness; the response returned to this request can still be stale by one cycle.
+- **`NetworkFirst`** — attempts network first (optionally bounded by `networkTimeoutSeconds`); falls back to cache only on network failure/timeout. Appropriate for content that must be fresh when possible but should still work offline/flaky-network.
+- **`NetworkOnly`** — never touches the cache for this route. Use for anything that must never be served stale or never be persisted client-side (mutations, authenticated reads that are hard-blocked from caching).
+- **`ExpirationPlugin`** (`maxEntries`, `maxAgeSeconds`) — bounds a runtime cache's size/age; without it, a runtime cache used with `CacheFirst`/`StaleWhileRevalidate`/`NetworkFirst` grows unbounded. This does not apply to precache, which is version-bounded by the manifest itself.
+- **`cleanupOutdatedCaches`** (`workbox-precaching`) — removes precache caches from prior manifest versions on activate. Confirm this (or equivalent manual `activate`-event cache deletion, as shown in Vite-PWA's `injectManifest` example querying `manifestURLs` and deleting non-listed keys) is present before endorsing any precache-based strategy.
+
+## Vite-PWA config surface (when in use)
+
+- `generateSW` strategy: `runtimeCaching` array maps `urlPattern` → `handler` (`'CacheFirst'`, `'NetworkFirst'`, `'StaleWhileRevalidate'`, `'NetworkOnly'`, etc.) + `options` (`cacheName`, `expiration`, `cacheableResponse`). Confirm every `runtimeCaching` entry's `urlPattern` is scoped tightly enough that it does not accidentally net authenticated API routes into a `CacheFirst` bucket meant for fonts/static assets.
+- `injectManifest` strategy: a custom `sw.ts`/`sw.js` source, precache manifest injected via `self.__WB_MANIFEST`. Review the custom source directly — Vite-PWA does not add any safety net here; every strategy choice, `activate` cleanup, and `skipWaiting`/`clientsClaim()` call is entirely the author's responsibility.
+- `clientsClaim()` + `self.skipWaiting()` — needed so a newly activated service worker takes control of open clients immediately rather than waiting for a full reload; absence of these (or an equivalent deliberate "update available, reload?" UX) means users can be stuck on stale app-shell logic indefinitely even after a successful deploy.
+
+## Verification targets
+
+- Confirm the strategy name in code/config against this file's semantics table, then confirm current behavior via Context7 before finalizing — do not rely on the strategy's *name* alone (e.g., "NetworkFirst" implementations have varied `networkTimeoutSeconds` defaults across versions).
+- For any runtime-cached route, confirm an `ExpirationPlugin` (or Vite-PWA `expiration` option) is present with a `maxAgeSeconds`/`maxEntries` bound appropriate to the route's sensitivity and volatility.
+- For precache, confirm `cleanupOutdatedCaches` or equivalent manual `activate` cleanup runs so superseded manifest versions are purged.
+
+## High-risk assumptions to kill
+
+- "Precache is basically cache-first" — precache bypasses HTTP entirely; runtime `CacheFirst` still makes a real network request on a cache miss.
+- "`StaleWhileRevalidate` means the user always gets fresh data" — the response served to the *current* request can be a stale copy; freshness only improves for the *next* request.
+- "No `ExpirationPlugin` is fine, the cache will sort itself out" — Cache API storage does not auto-evict; unbounded runtime caches grow until storage quota pressure causes browser-driven eviction, which is unpredictable and not a substitute for a deliberate policy.
+- "We use `generateSW`, so Vite-PWA handles safety for us" — `generateSW` only wires the strategy the author picked in `runtimeCaching`; it does not choose a safe strategy per route automatically or exclude authenticated routes on its own.

package/skills/frontend/ssr-hydration-streaming-diagnosis/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: ssr-hydration-streaming-diagnosis
+description: Diagnoses hydration-mismatch errors and streaming/Suspense-boundary structural issues to their specific root cause — non-deterministic rendering source, missing error boundary, serial data-fetch waterfall, or premature auth-unchecked streaming — grounded in the exact React/Next.js version's diagnostic behavior.
+allowed-tools: Read Grep Glob
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-07-02"
+  category: observability
+---
+
+# SSR Hydration & Streaming Diagnosis
+
+## Purpose
+
+Diagnose hydration-mismatch errors and streaming/Suspense-boundary structural issues to their specific root cause, without collapsing every hydration warning into a reflex `suppressHydrationWarning` fix or every streaming complaint into "wrap it in Suspense." This skill exists so root-cause identification — non-deterministic rendering source, missing error boundary, serial fetch waterfall, or auth-unchecked premature streaming — happens before any fix is proposed, and so that fix proposal never substitutes for diagnosis.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- diagnose a hydration-mismatch error or console warning (React 18 warning-style or React 19 diff-style),
+- investigate a TTFB/LCP regression that followed an SSR or streaming change,
+- review why a Suspense-wrapped section crashes to blank instead of degrading gracefully,
+- review a new Suspense/error-boundary tree design before it ships.
+
+Do not use this skill for:
+
+- state/store serialization design decisions with no specific mismatch or streaming symptom — that is `state-management-decision-review`,
+- route-tree or code-splitting review unrelated to SSR/streaming mechanics — that is `routing-navigation-review`,
+- generic component decomposition or state-placement review — that is `react-component-architecture-review`.
+
+## Context7 Documentation Protocol
+
+- Resolve `/reactjs/react.dev` before diagnosing any hydration-mismatch error. The diagnostic error *format itself* is version-specific: React 19 emits a single detailed diff-style error (`Hydration failed because the server rendered HTML didn't match the client...` with a `+ Client` / `- Server` diff), while React 18 emits separate, less-specific warnings and silently "patches" mismatched nodes instead of remounting from the nearest Suspense boundary. Diagnosing a React 18 warning against the React 19 mental model (or vice versa) produces a wrong root-cause guess.
+- Before recommending a fix, confirm the installed React major version (check `package.json` / lockfile) and call `query-docs` scoped to that version for "hydration mismatch" and, if `use()` or a Suspense-wrapped fetch is involved, for "use hook Suspense error boundary."
+- Resolve `/vercel/next.js` and call `query-docs` scoped to the confirmed Next.js version before asserting streaming/Suspense-boundary semantics, `loading.js` behavior, or bot/crawler streaming exceptions — Next.js waits for all data fetching to finish before sending a fully rendered page to bots/crawlers instead of streaming progressively, which changes what "premature streaming" even means for that request path.
+- If Context7 is unavailable, fall back to the `official_docs` URLs in this skill's `metadata.json` and label every claim `documentation-based, unverified against current release`.
+
+## Lean operating rules
+
+- Root cause before fix, always. Do not propose `suppressHydrationWarning`, a Suspense-boundary restructure, or a caching change until the specific mechanism is named and evidenced. A fix proposed before root cause is identified is a guess wearing a diagnosis costume.
+- The four canonical hydration-mismatch causes per React's own diagnostic message are: a server/client branch (`typeof window !== 'undefined'`), variable input (`Date.now()`, `Math.random()`), locale-dependent formatting that differs between server and client, and external/changing data rendered without a matching snapshot sent alongside the HTML — plus invalid HTML tag nesting as a fifth, structural cause. Map the reported mismatch to one of these five before naming a fix.
+- `suppressHydrationWarning` is a one-level-deep escape hatch, not a fix. It is acceptable only when the root cause is a genuinely unavoidable non-determinism (for example, a legitimately locale/timezone-dependent timestamp) and only with a documented justification comment at the call site. Treat any use of it without an identified root cause and written justification as a rejected finding, not an approved one.
+- Since React 18, a hydration mismatch from missing/extra text content is treated as an error, not a soft warning: React discards and re-renders client-side from the nearest `<Suspense>` boundary rather than patching individual nodes. This means the blast radius of a mismatch is bounded by Suspense placement — a missing or too-coarse Suspense boundary turns a small mismatch into a large client re-render.
+- Every component that suspends via `use()` on a Promise (or any Suspense-triggering data read) must have a paired Error Boundary somewhere in its ancestor tree, because a rejected Promise propagates to the nearest Error Boundary, not the nearest Suspense fallback. A Suspense boundary with no ancestor Error Boundary is a crash-to-blank defect, not a style preference.
+- Suspense boundaries that are too coarse (one boundary wrapping an entire page, mixing fast and slow content) block fast content behind the page's slowest fetch. Prefer sibling Suspense boundaries around independently-loading sections so each streams in as its own data resolves, per Next.js's own parallel-streaming pattern.
+- A fetch that depends on the result of a prior fetch (for example, fetching playlists that require an artist ID from a preceding fetch) is legitimately sequential — do not flag that as a waterfall defect. Only flag fetches that are data-independent but are still awaited one after another instead of started concurrently.
+- Streaming that flushes page structure or partial content to the client before an authorization check has resolved is a potential information-disclosure defect, not a performance nitpick — escalate it, do not file it as a UX note.
+- Never execute, build, or run application code as part of this review; this is a static-review skill (Read/Grep/Glob only) — diagnose from the reported error text, the component/boundary source, and any network/fetch-order trace the user provides.
+
+## References
+
+Load these only when needed:
+
+- [Hydration mismatch diagnosis](references/hydration-mismatch-diagnosis.md) — use when diagnosing a specific hydration-mismatch error or warning to its root cause.
+- [Suspense and streaming structure review](references/suspense-streaming-structure.md) — use when reviewing or designing a Suspense/error-boundary tree, or diagnosing a TTFB/LCP regression or crash-to-blank symptom.
+- [Fetch waterfall and auth-timing review](references/fetch-waterfall-and-auth-timing.md) — use when diagnosing a sequential-fetch performance issue or reviewing whether streaming exposes content before authorization resolves.
+
+## Response minimum
+
+Return, at minimum:
+
+- the specific root-cause mechanism identified (or explicit statement that root cause is unresolved and more evidence is needed — never a guess presented as a diagnosis),
+- the React/Next.js major version the diagnosis was verified against,
+- evidence level (`documentation-based`, `repo evidence`, `user-provided evidence`, or `inference`) and what Context7 query grounded the claim,
+- the proposed fix scoped to the identified root cause, or explicit refusal to propose a fix until root cause is confirmed,
+- security/disclosure caveat if streaming-before-auth risk is present,
+- verdict: approve / approve-with-notes / block.

package/skills/frontend/ssr-hydration-streaming-diagnosis/metadata.json

@@ -0,0 +1,28 @@
+{
+  "id": "ssr-hydration-streaming-diagnosis",
+  "name": "SSR Hydration & Streaming Diagnosis",
+  "type": "skill",
+  "provider": "frontend",
+  "harnesses": [
+    "claude-code",
+    "cursor",
+    "codex",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Diagnoses hydration-mismatch errors and streaming/Suspense-boundary placement issues to their root cause, using framework-version-specific evidence rather than guesswork, with root-cause-before-fix and auth-before-stream as hard gates.",
+  "source_type": "original",
+  "official_docs": [
+    "https://react.dev/reference/react-dom/client/hydrateRoot",
+    "https://react.dev/reference/react/Suspense",
+    "https://react.dev/reference/react/use",
+    "https://nextjs.org/docs/app/building-your-application/rendering/server-components",
+    "https://web.dev/articles/optimize-lcp"
+  ],
+  "security_notes": "Never accept suppressHydrationWarning as the fix without a documented, unavoidable non-determinism justification; treat it as a rejected finding when used without an identified root cause. Treat streaming that flushes page structure or content before an authorization check resolves as a potential information-disclosure finding requiring escalation, not a performance note. Static-review-only skill: it reads and greps component/boundary source and reported error text but never executes, builds, or runs application code.",
+  "last_verified": "2026-07-02",
+  "path": "skills/frontend/ssr-hydration-streaming-diagnosis",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}