@raishin/vanguard-frontier-agentic 3.0.2 → 3.1.0

package/skills/frontend/ssr-hydration-streaming-diagnosis/references/fetch-waterfall-and-auth-timing.md

@@ -0,0 +1,64 @@
+# Fetch Waterfall and Auth-Timing Review
+
+Use this reference when diagnosing a sequential-fetch performance issue, or when reviewing whether streaming exposes page structure or content before an authorization check has resolved.
+
+## What people get wrong
+
+Two separate bad assumptions show up together often enough to warrant one reference:
+
+> "These fetches run one after another because that's just how `await` works" — sometimes true, sometimes a waterfall defect.
+
+> "Streaming just sends HTML progressively, auth isn't a streaming concern" — wrong when the streamed content itself is the thing that needed authorization.
+
+Both require actually tracing the await order and the request lifecycle, not pattern-matching on the presence of `await` or `<Suspense>`.
+
+## Waterfall diagnosis: sequential vs. genuinely dependent
+
+Not every sequential `await` chain is a defect. Next.js's own data-fetching guidance shows a legitimately sequential case: fetching an artist's playlists requires the artist's ID, which only exists after the artist fetch resolves. That is a genuine data dependency — the second fetch cannot start before the first resolves, and flagging it as a waterfall defect is a false positive.
+
+The defect pattern is different: two (or more) fetches that do **not** depend on each other's output, but are still written with sequential `await` calls, so the second fetch doesn't start until the first finishes — costing the sum of both latencies instead of the max.
+
+### Diagnostic procedure
+
+1. For each pair of fetches in the flagged code path, determine: does fetch B use any value produced by fetch A (an ID, a token, a computed parameter)? If yes, sequential `await` is correct — do not flag it.
+2. If fetch B does not depend on fetch A's output but is still written after `await fetchA()`, this is a real waterfall. Recommend starting both concurrently — begin the fetch (don't await it immediately) and consume both results together, or use per-section Suspense boundaries with each section starting its own fetch independently so they resolve in parallel rather than being serialized by a shared parent awaiting both in sequence.
+3. Confirm the recommended restructuring doesn't accidentally introduce a request that now fires on every render when it previously ran once — verify fetch caching/memoization semantics for the confirmed framework version via Context7 before asserting the parallelized version is still correct.
+
+### Fix framing
+
+Do not just say "parallelize this." State which specific fetches are independent (by name/file:line), what the current serialized cost is (sum of both fetches' latency), and what the corrected cost would be (max of both). A vague "these could probably be parallel" is not a completed diagnosis.
+
+## Auth-timing and premature streaming
+
+Streaming sends the response progressively as chunks resolve, which means part of the response can reach the client (and be rendered, or at minimum be visible in dev tools / network trace) before the entire request lifecycle — including any authorization check — has completed, if the authorization check is not structured to gate the stream's start.
+
+### The specific defect pattern
+
+A route or component streams protected content (page structure that reveals a resource exists, partial data, or a shell that implies the current user has access) **before** the code path that verifies the requester is authorized to see that content has resolved and short-circuited on failure. This differs from a plain performance concern: the risk is that an unauthorized request can observe something about a protected resource — its existence, its shape, or fragments of its data — purely from what streamed before the authorization check would have blocked it.
+
+### Review procedure
+
+1. Identify the authorization check for the route/resource in scope (session/role/ownership verification).
+2. Trace what streams (renders, sends data, or resolves a Suspense boundary) before that authorization check has run and been evaluated.
+3. If anything protected-resource-specific streams before the authorization check resolves and can fail, treat this as a potential information-disclosure finding and escalate — do not file it as a performance observation.
+4. Distinguish this from the unprotected-shell case: a generic loading skeleton with no resource-specific information (no IDs, no titles, no counts) streaming before auth resolves is not a disclosure risk by itself. The defect is specifically protected-resource-specific content or metadata reaching the client stream ahead of the authorization gate.
+5. Note the bot/crawler exception when relevant: Next.js does not stream progressively to bots/crawlers — it waits for full data resolution first — so a premature-streaming disclosure concern for a browser request does not automatically apply the same way to a bot-facing response, and conflating the two produces an inaccurate threat model.
+
+### Fix framing
+
+The correct fix is almost always structural: perform the authorization check synchronously before starting the response (or before the first byte that carries resource-specific content is flushed), not "add a loading spinner" or "move the check earlier in the component tree" without confirming it actually runs before the first protected content leaves the server.
+
+## Adversarial checklist
+
+- For each flagged sequential-fetch pair: is there an actual data dependency, or is this a real waterfall?
+- For the proposed parallelization: does it change caching/memoization semantics for the confirmed framework version?
+- Does any protected-resource-specific content (not a generic skeleton) stream before the authorization check has resolved and could fail?
+- Is the auth-timing concern being applied correctly to the browser-facing path, given that bot/crawler responses do not stream progressively in the first place?
+
+## When to push back
+
+Push back if the user asks to:
+
+- "just parallelize everything" without tracing which fetches are actually independent,
+- move an authorization check later in the render tree "to make the page feel faster," when that change would let protected content start streaming before the check resolves,
+- treat a generic loading skeleton with zero resource-specific data as an auth-timing risk — that is a false positive that dilutes real findings.

package/skills/frontend/ssr-hydration-streaming-diagnosis/references/hydration-mismatch-diagnosis.md

@@ -0,0 +1,66 @@
+# Hydration Mismatch Diagnosis
+
+Use this reference when a hydration-mismatch error or warning has been reported and the root cause is not yet identified.
+
+## What people get wrong
+
+The reflex move is:
+
+> There's a hydration warning in the console. Add `suppressHydrationWarning` and move on.
+
+That is not a diagnosis. It is silence applied to a symptom. `suppressHydrationWarning` only works one level deep, does not make the underlying value consistent, and React explicitly documents it as an escape hatch that should not be overused. Applying it before naming the mechanism means the next mismatch — possibly a real one, possibly deeper in the tree — gets silently absorbed into the same reflex.
+
+## Version-specific error format — check this first
+
+The shape of the error itself tells you which React major version you are diagnosing against, and the two shapes carry different diagnostic information:
+
+- **React 19+**: a single detailed error with an inline diff (`+ Client` / `- Server`) pinpointing the exact mismatched node, plus an enumerated list of the five canonical causes in the error text itself, plus a link to `https://react.dev/link/hydration-mismatch`.
+- **React 18**: hydration mismatches from missing/extra text content are treated as errors (not silently patched), and React reverts to client rendering up to the closest `<Suspense>` boundary — but the console output is less specific about *which* node and *why* than React 19's diff-style message.
+- **Pre-18**: React would attempt to "patch up" individual mismatched nodes on the client — a materially different (and less safe) recovery behavior than 18+.
+
+Confirm the installed React major version before interpreting the error text. Diagnosing a React 18 mismatch as if it carries a React 19 diff, or vice versa, leads to misreading what the error is actually telling you.
+
+## The five canonical causes
+
+React's own diagnostic message enumerates these. Map the specific reported mismatch to one of them before proposing anything:
+
+1. **Environment branch** — `typeof window !== 'undefined'` (or equivalent) used to render different output on server vs. client.
+2. **Variable input** — `Date.now()`, `Math.random()`, or any value that changes between the server render and the client's initial render.
+3. **Locale-dependent formatting** — `toLocaleDateString()`, `Intl.NumberFormat`, or similar, where the server's locale/timezone differs from the client's.
+4. **Unsent external state** — data that changed between server render and client hydration, rendered without the server sending a snapshot of the value it used alongside the HTML.
+5. **Invalid HTML nesting** — structurally invalid tag nesting (e.g., a `<div>` inside a `<p>`) that the browser silently repairs during parsing, producing a DOM tree that no longer matches what React expects to hydrate.
+
+A sixth, non-code cause exists and should not be misdiagnosed as a code defect: a browser extension mutating the DOM before React hydrates. If the mismatch is isolated to attributes an ad-blocker or password-manager extension is known to inject, say so explicitly rather than chasing a phantom code path.
+
+## Diagnostic procedure
+
+1. Confirm the React major version.
+2. Read the full error/diff text (React 19) or reproduce and inspect the DOM/console output (React 18) — do not diagnose from a truncated paste.
+3. Search the flagged component (and its ancestors up to the nearest previous hydration boundary) for each of the five causes in order: environment branches, non-deterministic values, locale formatting calls, externally-sourced data without a matching server-sent snapshot, and invalid nesting.
+4. State the identified cause explicitly, citing the file:line and the specific expression responsible.
+5. Only after the cause is named, propose a fix scoped to that cause — see fix mapping below.
+
+## Fix mapping — do not default to suppression
+
+| Root cause | Correct fix | `suppressHydrationWarning` acceptable? |
+|---|---|---|
+| Environment branch (`typeof window`) | Defer the branch to `useEffect`/client-only render after mount, or use a library-provided SSR-safe check | No |
+| `Date.now()` / `Math.random()` | Compute the value once on the server and pass it down as a prop/serialized snapshot; do not recompute on the client | No |
+| Locale/timezone formatting | Pass the server's resolved locale/timezone explicitly instead of relying on ambient `Intl` defaults, or accept the value as genuinely unavoidable | Only if genuinely unavoidable, with a written justification comment |
+| Unsent external/changing data | Send a snapshot of the data used for the server render down to the client so the client's first render matches it | No |
+| Invalid HTML nesting | Fix the markup structure | No |
+| Browser extension interference | No code fix; document as an environment artifact, do not chase it as a defect | N/A |
+
+The only row where `suppressHydrationWarning` is legitimate is the locale/timezone row, and only when the mismatch truly cannot be eliminated (for example, a "time ago" display that is inherently observer-relative) — and even then, it requires a comment at the call site stating why suppression is correct, not merely convenient.
+
+## Adversarial checklist
+
+Before closing a hydration-mismatch diagnosis, answer these:
+
+- Which of the five canonical causes (or the extension exception) does the evidence actually point to — not which one is the easiest to write a fix for?
+- Was the diagnosis made against the correct React-major-version error format?
+- If the fix is `suppressHydrationWarning`, is there a written justification, and is the non-determinism actually unavoidable rather than just inconvenient to eliminate?
+- Does the fix address the value/branch that differs, or does it just make the warning go away while the divergent values still exist?
+- Is this an isolated single-node mismatch, or does the same root cause recur across multiple components (suggesting a shared utility/hook is the real source)?
+
+If these cannot be answered, the diagnosis is not complete — say so rather than proposing a fix.

package/skills/frontend/ssr-hydration-streaming-diagnosis/references/suspense-streaming-structure.md

@@ -0,0 +1,63 @@
+# Suspense and Streaming Structure Review
+
+Use this reference when reviewing or designing a Suspense/error-boundary tree, or diagnosing a TTFB/LCP regression or a crash-to-blank symptom tied to streaming.
+
+## What people get wrong
+
+The naive story is:
+
+> Wrap it in `<Suspense>` and streaming just works.
+
+Incomplete. A `<Suspense>` boundary controls *what shows while content is pending* and *how far a hydration-mismatch re-render blast radius reaches*. It does not, by itself, handle rejection (that is the Error Boundary's job), does not make sibling sections stream independently unless they are wrapped in their own boundaries, and does not change fetch ordering — a slow fetch inside a narrow Suspense boundary is still slow; the boundary just contains the wait to that section instead of blocking the whole page.
+
+## Officially grounded shape
+
+- `use()` reading a pending Promise causes the calling component to suspend; React shows the nearest `<Suspense fallback>` while pending.
+- If the Promise **rejects**, the error propagates to the nearest **Error Boundary**, not the nearest Suspense fallback. A component that calls `use()` (or otherwise suspends on a rejectable data source) with a Suspense boundary but no ancestor Error Boundary will crash to an unhandled error when that data source fails — there is no fallback UI for the rejection case.
+- Since React 18, a hydration mismatch causes React to discard and re-render client-side starting from the **nearest Suspense boundary**, not the whole tree and not just the single mismatched node. Suspense placement therefore directly bounds mismatch blast radius, independent of streaming concerns.
+- Next.js's own streaming guide demonstrates wrapping **independent** async sections in **separate, sibling** `<Suspense>` boundaries so each streams in as its own data resolves, rather than one boundary gating the whole page behind its slowest child.
+- Streaming can be implemented via a route's `loading.js` file or via explicit `<Suspense>` around a component. For bots/crawlers, Next.js waits for all data fetching to finish and sends the fully rendered page rather than streaming progressively — a bot-facing request does not get the same partial-render exposure window a browser request does, which matters when reasoning about what a "premature" stream can leak to which caller.
+
+## Non-negotiable design rules
+
+### 1. Every suspending read needs a paired Error Boundary
+
+Do not approve a Suspense boundary wrapping a `use()` call, a suspending fetch, or any Suspense-triggering data read without confirming an Error Boundary exists somewhere in its ancestor chain. If the user has not added one, this is a defect: on rejection, the user sees an unhandled crash/blank instead of a fallback message.
+
+### 2. Boundary granularity should match content speed, not code convenience
+
+One `<Suspense>` around an entire page is the easiest thing to write and the worst thing to ship when the page mixes fast content (e.g., a nav shell) with slow content (e.g., a report requiring heavy aggregation). The fast content is held hostage by the slow content's fallback. Prefer sibling boundaries per independently-loading section, following the pattern Next.js documents for parallel streaming.
+
+### 3. Boundary granularity also bounds mismatch blast radius
+
+A too-coarse boundary is a double defect: it blocks fast content behind slow content *and* it means any hydration mismatch inside that huge boundary forces React to discard and re-render the entire boundary's subtree client-side, not just the small mismatched region. Narrower, purpose-scoped boundaries reduce both problems simultaneously.
+
+### 4. A Suspense fallback is not a substitute for a loading-state design review
+
+Confirm the fallback communicates something coherent (skeleton matching the eventual layout, or a clear loading indicator) rather than an empty or jarring placeholder — a correct boundary with a poor fallback is still a shippable defect, just a lower-severity one than a missing Error Boundary.
+
+## Minimal safe review flow
+
+1. Map every `<Suspense>` boundary in the tree under review and what it wraps.
+2. For each boundary, identify what suspends inside it (a `use()` call, a Server Component awaiting a fetch, a lazy-loaded component) and confirm an Error Boundary exists in its ancestor chain — if not, that is a defect (see `fetch-waterfall-and-auth-timing.md`'s parent skill rule: crash-to-blank is not acceptable).
+3. For each boundary, ask whether it wraps content of meaningfully different load-latency profiles. If yes, and content is independent, recommend splitting into sibling boundaries per the Next.js parallel-streaming pattern.
+4. For each boundary wrapping content that depends on a prior async result (a genuinely sequential dependency, e.g., needing an ID from a previous fetch before the next component can render), confirm the nesting reflects that dependency rather than an accidental structure that could be flattened.
+5. Confirm the fallback UI is coherent, not a placeholder afterthought.
+6. State the verdict per boundary, not just for the tree as a whole — a tree can be correct in three boundaries and defective in one.
+
+## High-risk assumptions to kill
+
+- "It's wrapped in Suspense, so errors are handled" — Suspense handles pending state, not rejection.
+- "One Suspense boundary at the top is simpler and streaming still works" — technically true, but it defeats the purpose of granular streaming and maximizes mismatch blast radius.
+- "The fallback shows briefly so its content doesn't matter" — a jarring or mismatched-size fallback causes layout shift on resolve, which is a measurable UX/performance regression, not a cosmetic detail.
+- "Bots see the same partial-render window a browser does" — they do not; Next.js waits for full data resolution before responding to bots/crawlers, which changes threat/exposure reasoning for that path specifically.
+
+## When to push back
+
+Push back if the user asks to:
+
+- remove a Suspense boundary "to make the loading flicker go away" without addressing the underlying slow fetch,
+- wrap a suspending, rejectable data read in Suspense with explicit instruction to skip the Error Boundary "for now,"
+- collapse several independently-loading sections into one shared boundary purely to reduce the number of `<Suspense>` tags in the file.
+
+Those trade a visible symptom for a worse, less visible one (either a crash-to-blank on failure, or slow content gating fast content).

package/skills/frontend/state-management-decision-review/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: state-management-decision-review
+description: Reviews whether data is correctly classified as server state, client state, or derived state, and whether the resulting store/cache design (query keys, invalidation, optimistic-update rollback, SSR instantiation, selector shape) avoids duplication, stale-data bugs, and unnecessary re-render cascades.
+allowed-tools: Read Grep Glob
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-07-02"
+  category: architecture
+---
+
+# State Management Decision Review
+
+## Purpose
+
+Review a proposed or existing state-management design without re-litigating routing/URL-state ownership, API contract shape, or SSR hydration-mismatch diagnosis in every response. Most state-management bugs trace back to a single category error: treating server-owned data (fetched from an API, subject to staleness, shared across users or tabs) as if it were client-owned data (form input, UI toggles, ephemeral interaction state). Once that error is made, every downstream decision — where to put the data, when to refetch it, how to invalidate it, whether an update needs a rollback path — compounds it. This skill exists to catch that root-cause error early and to evaluate the caching/invalidation strategy and store topology against two measurable failure modes: stale/duplicated data and unnecessary re-render cascades.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- review a PR that introduces new fetching, caching, or store logic,
+- diagnose a "stale data after save" or "the list didn't update after I created/deleted an item" bug report,
+- diagnose a "page freezes while typing" or "every keystroke re-renders half the tree" performance complaint tied to a shared store,
+- evaluate a proposal to introduce a new state-management library or a new global store,
+- audit an existing store for entities that duplicate or conflate server-fetched data with client-only data.
+
+Do not use this skill for:
+
+- routing/URL-state ownership review (filters, pagination, tabs that should be reconstructable from the URL) — that is `routing-navigation-review`,
+- BFF/API contract shape, request/response schema, or endpoint design review — that is `api-integration-contract-review`,
+- SSR hydration mismatch diagnosis unrelated to store/query-client serialization (server/client markup divergence) — that is `ssr-hydration-streaming-diagnosis`. This skill only covers SSR store/queryClient *instantiation* (per-request vs. shared singleton), not hydration mismatch mechanics.
+
+## Context7 Documentation Protocol
+
+- Resolve `/tanstack/query` with `resolve-library-id` before asserting any caching default (`staleTime`, `gcTime`, `refetchOnWindowFocus`) — these are documented defaults, not universal truths, and the repo's installed major version governs behavior. `staleTime` defaults to `0` (query is considered stale immediately after any successful fetch) and `refetchOnWindowFocus` defaults to `true`; do not assume the reviewed repo has left these at default without checking the `QueryClient` construction site.
+- Before flagging an optimistic-update pattern as missing rollback, call `query-docs` on `/tanstack/query` for "optimistic updates" to confirm the current documented shape (`onMutate` cancels in-flight queries, snapshots prior data, returns it as mutation context; `onError` restores the snapshot from that context; `onSettled` invalidates). Do not invent an alternate rollback API.
+- Resolve `/pmndrs/zustand` with `resolve-library-id` before recommending a selector-based re-render fix. Confirm current `useShallow` import path and behavior via `query-docs` before telling a user to add it — the import path (`zustand/react/shallow` vs `zustand/react`) and default `Object.is` comparator behavior are version-sensitive.
+- Before approving a `persist` middleware usage that touches auth/session data, call `query-docs` on `/pmndrs/zustand` for "persist middleware" to confirm current `partialize` and `storage` options exist and are the documented way to exclude sensitive fields — do not assume a field-exclusion API without checking it.
+- If Context7 is unavailable for either library, fall back to the `official_docs` URLs in this skill's `metadata.json` and label every caching-default or API-shape claim `documentation-based, verify against installed version` rather than stating it as settled fact.
+- Read `package.json` first to confirm which server-state library (if any) is actually installed and its major version. Do not recommend a fix keyed to an API that the installed major version does not have.
+
+## Lean operating rules
+
+- Build the entity classification table before evaluating anything else. Every piece of state in scope must land in exactly one bucket: **server state** (fetched from an API/DB, has a remote source of truth, can go stale, is potentially shared across users or tabs), **client state** (exists only in this session — form inputs before submit, modal open/closed, hover/focus, drag position), or **derived state** (computed from server and/or client state — never independently stored). Do not evaluate caching strategy before this table exists; the table is the review's foundation, not an afterthought.
+- Any entity classified as server state that is held in `useState`/`useReducer`/a plain client store instead of a query/cache library is a category-error finding, not a style note — it is the root cause of most manual-refetch and stale-cache bugs the skill exists to catch.
+- Any entity classified as derived state that is independently stored (rather than computed on read, in a selector, or in a memoized derivation) is a duplication finding — it can drift from its inputs and is a second, harder-to-find source of staleness.
+- For every server-state entity, require an explicit, inspectable cache key and an explicit invalidation trigger (what mutation, what event, or what time-based policy causes a refetch). "It'll refetch eventually" without a named trigger is not an answer.
+- For every optimistic update (a mutation that updates the UI before the server confirms), require a paired rollback path (`onError` restoring a snapshot taken in `onMutate`) per the current documented pattern. An optimistic update with no rollback path is a HARD STOP, not a note — it means a failed mutation leaves the UI showing state the server never accepted, with no correction mechanism.
+- For SSR applications, require that the query client and any global store be instantiated per-request (inside component state / a request-scoped factory), never as a module-level singleton created once at import time. A module-level singleton in SSR is a HARD STOP — it is a cross-request/cross-user data-leak vector, not merely a performance concern.
+- Do not accept a re-render-cascade "fix" (memoization, selector narrowing, splitting a store) without profiler evidence (a before/after render count or a flame-graph excerpt). A fix justified only by "this should reduce re-renders" is speculation, not a verified finding — require the evidence or explicitly flag it as unverified.
+- Do not recommend introducing a new global store as the default fix for a data-caching problem that a server-state library already solves (deduping, background refetch, invalidation). Naming a new store as the fix for a caching bug is itself a finding to push back on.
+- Never execute, build, or run application code as part of this review; this is a static-review skill (Read/Grep/Glob only). Profiler evidence must come from the user/PR description, not from live reproduction performed by this skill.
+- Treat any store or persisted-storage design that writes auth tokens, session identifiers, or PII to `localStorage`/`sessionStorage` (directly or via a `persist` middleware without a `partialize` exclusion) as a security-relevant finding requiring explicit encryption/expiry/justification — do not wave it through as a caching-pattern detail.
+
+## References
+
+Load these only when needed:
+
+- [Review workflow and findings contract](references/workflow-and-output.md) — use for the step-by-step review procedure, the classification/decision tree, and the required output shape.
+- [Server-state caching and invalidation](references/server-state-caching-and-invalidation.md) — load only when reviewing query-key design, invalidation triggers, optimistic-update rollback, or SSR query-client instantiation.
+- [Client-store topology and re-renders](references/client-store-topology-and-rerenders.md) — load only when reviewing store-slice design, selector shape, `useShallow` usage, or a reported re-render-cascade / typing-jank complaint.
+
+## Response minimum
+
+Return, at minimum:
+
+- the entity classification table (server / client / derived) for every entity in scope,
+- for each server-state entity: its cache key, its invalidation trigger, and (if applicable) its optimistic-update rollback path,
+- for each client-store slice reviewed: its selector shape and whether it is exposed to unnecessary re-render risk,
+- for bug diagnosis: a root-cause statement distinguishing stale-cache vs. race-condition vs. re-render-cascade vs. normalization/duplication bug — not a vague "state management issue",
+- evidence level per finding (`repo evidence`, `documentation-based`, or `inference`),
+- verdict (approve / approve-with-notes / block), with HARD STOPS (missing rollback, SSR singleton) called out separately from lower-severity notes,
+- open questions or scope the review could not cover (e.g., "re-render claim requires profiler evidence to confirm").

package/skills/frontend/state-management-decision-review/metadata.json

@@ -0,0 +1,30 @@
+{
+  "id": "state-management-decision-review",
+  "name": "State Management Decision Review",
+  "type": "skill",
+  "provider": "frontend",
+  "harnesses": [
+    "claude-code",
+    "cursor",
+    "codex",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Reviews whether data is correctly classified as server state vs. client state vs. derived state, and whether the resulting store/cache design (query keys, invalidation triggers, optimistic-update rollback, SSR instantiation, selector shape) avoids duplication, stale-data bugs, and unnecessary re-render cascades, grounding every TanStack Query and Zustand claim via Context7 against the repo's confirmed installed version.",
+  "source_type": "original",
+  "official_docs": [
+    "https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults",
+    "https://tanstack.com/query/latest/docs/framework/react/guides/optimistic-updates",
+    "https://tanstack.com/query/latest/docs/framework/react/guides/ssr",
+    "https://zustand.docs.pmnd.rs/getting-started/introduction",
+    "https://zustand.docs.pmnd.rs/hooks/use-shallow",
+    "https://zustand.docs.pmnd.rs/middlewares/persist",
+    "https://react.dev/learn/managing-state"
+  ],
+  "security_notes": "Static-review-only skill: it reads and greps source but never executes, builds, or runs application code. Reject any store design that persists auth tokens, session identifiers, or PII to localStorage/sessionStorage without an explicit encryption/expiry justification or a documented partialize exclusion, and reject any SSR queryClient/store pattern that instantiates as a module-level singleton, which risks cross-request/cross-user data leakage. Missing optimistic-update rollback and SSR singleton instantiation are treated as HARD STOP findings, not style notes.",
+  "last_verified": "2026-07-02",
+  "path": "skills/frontend/state-management-decision-review",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/frontend/state-management-decision-review/references/client-store-topology-and-rerenders.md

@@ -0,0 +1,81 @@
+# Client-Store Topology and Re-Renders
+
+Use this reference only when reviewing store-slice design, selector shape, `useShallow` usage, or a reported re-render-cascade / "typing lags" complaint tied to a client store. Grounded against Zustand (`/pmndrs/zustand`) — verify version-sensitive import paths and defaults via Context7 before asserting them as the reviewed repo's behavior.
+
+## What people get wrong
+
+The naive story is:
+
+> I put everything in one global store because it's easier than deciding what goes where.
+
+That is not a topology decision — it is the absence of one, and it has a specific, predictable cost: every component that reads *any* field from that store re-renders on *every* write to that store unless each consumer's selector is narrow enough to opt out. A single monolithic store with wide, whole-store selectors (`const state = useStore()`) is the most common root cause of "every keystroke re-renders half the tree" complaints — not React itself, not the framework, the subscription shape.
+
+The second common wrong assumption:
+
+> Memoizing the component (`React.memo`) will fix the re-render cascade.
+
+Often wrong, or incomplete. `React.memo` prevents a re-render caused by a *parent* re-rendering with the same props; it does nothing for a re-render caused by the component's *own* subscription to a store firing because some unrelated field in that store changed. If the component calls `useStore((s) => s)` or otherwise subscribes to the whole store, `React.memo` will not help — the selector itself is the leak.
+
+## Officially grounded shape
+
+Per current Zustand docs (verify against installed major via Context7):
+
+- **Selectors control subscription granularity.** `useStore((state) => state.field)` subscribes only to `field`; the component re-renders only when the *selector's return value* changes (by default, via `Object.is` reference equality), not on every store write.
+- **Object/array selectors need shallow comparison.** A selector that returns a freshly-constructed object or array on every call — `useStore((state) => ({ nuts: state.nuts, honey: state.honey }))` — produces a new reference every render even when `nuts` and `honey` are unchanged, defeating the point of selecting narrowly. The documented fix is `useShallow` from `zustand/react/shallow` (or `zustand/react` depending on installed version — confirm the current import path via Context7 before citing it), which memoizes the selector so the component only re-renders when the shallow-compared output actually changes.
+- **Selecting the whole store defeats granularity entirely.** `const state = useStore()` (no selector function) subscribes the component to every field; this is the store-topology equivalent of the server-state "no query key scoping" mistake — it works, until it is the reason everything re-renders.
+- **`persist` middleware controls what is written to storage, not what triggers re-renders.** Do not conflate persistence configuration with subscription/selector configuration; they solve different problems and a fix for one does not address the other.
+
+## Non-negotiable design rules
+
+### 1. Slice the store by consumer lifecycle and update frequency, not by feature name alone
+
+Fields that change on every keystroke (a search-box draft value) and fields that change rarely (a user's theme preference) do not belong in the same store if components reading the rare field would otherwise re-render on every keystroke via a wide selector. Prefer multiple narrow stores or well-separated slices over one store with defensive selectors bolted on afterward.
+
+### 2. Every consumer selects only the fields it reads
+
+A component that reads `user.name` should select `(state) => state.user.name`, not `(state) => state.user` (unless it genuinely reads the whole `user` object) and never `(state) => state` (unless it is a debug/devtools consumer). Grep for `useStore(state => state)` or a bare `useStore()` call with no selector as a first-pass smell.
+
+### 3. Object/array-returning selectors require `useShallow` or an equivalent stable-reference strategy
+
+A selector returning an inline object or array literal without `useShallow` is a re-render-cascade finding, not a style nit — it produces a new reference on every store update regardless of whether the selected values changed, defeating the selector's purpose. Confirm the current `useShallow` import path via Context7 before recommending the fix, since it has moved across major versions.
+
+### 4. Do not accept a re-render fix without profiler evidence
+
+Per `SKILL.md`: a memoization, selector-narrowing, or store-splitting change proposed as the fix for a reported "typing lags" or "re-renders too much" complaint must be accompanied by a before/after render count or flame-graph excerpt. "This should reduce re-renders" is a hypothesis; treat it as `inference`-level evidence until measured, and say so explicitly rather than approving it as verified.
+
+### 5. Server-owned data does not belong in a client store's slice design at all
+
+If the classification step (see `workflow-and-output.md`) placed an entity in a client store but it is actually server state, the fix is reclassification and migration to a query/cache library — not a more clever selector. Do not let a well-designed selector distract from the fact that the entity is in the wrong system entirely.
+
+## Minimal safe implementation flow
+
+1. Classify the entity as client state (see `workflow-and-output.md` decision tree) — confirm it is not actually server state wearing a client-store costume.
+2. Decide which store/slice it belongs in based on update frequency and consumer lifecycle, not just feature grouping.
+3. For each consumer, write the narrowest selector that returns exactly the fields it reads.
+4. If the selector returns an object or array literal, wrap it in `useShallow` (confirm current import path via Context7) or restructure to select primitives individually.
+5. If a re-render complaint motivated the review, capture profiler evidence before and after the change to confirm the fix actually reduced render count.
+
+## High-risk assumptions to kill
+
+- "One global store is simpler" — simpler to set up, not simpler to reason about once selectors are wide and re-renders cascade.
+- "`React.memo` will fix it" — does not help when the component's own store subscription is the source of the re-render.
+- "Selecting an object is fine, it's just one extra render" — one extra render per keystroke, multiplied across every consumer with the same pattern, is the actual complaint being diagnosed.
+- "We'll add `useShallow` later if it becomes a problem" — retrofitting selector discipline after a store has many wide-selector consumers is materially harder than establishing the pattern from the first consumer.
+- "Increasing `staleTime` will fix the re-render complaint" — `staleTime` is a TanStack Query caching concept and has no effect on Zustand (or any client store) subscription/re-render behavior; do not let a caching-policy fix stand in for a selector fix. See `server-state-caching-and-invalidation.md` for the caching side of this distinction.
+
+## Safe verification targets
+
+- Grep for `useStore(` (or the project's actual store hook name) call sites with no selector argument, or with `state => state` — whole-store subscriptions.
+- Grep for selector bodies returning an object or array literal (`=> ({`, `=> [`) and check whether `useShallow` wraps the call.
+- Confirm the `useShallow` import path (`zustand/react/shallow` vs `zustand/react`) matches the installed Zustand major version.
+- For a reported re-render complaint, ask for or request a profiler render count/flame-graph excerpt scoped to the affected component before accepting a selector or memoization fix as verified.
+
+## When to push back
+
+Push back if the user asks for:
+
+- one monolithic store for the whole app "to keep things simple,"
+- a memoization or selector change presented as a confirmed fix with no profiler evidence,
+- a bare whole-store selector "because we need most of the fields anyway" without checking whether that is actually true per consumer.
+
+A store topology that is easy to set up and expensive to render is not a good trade — it is deferred cost, and it lands on every future consumer of that store, not just the one being reviewed.

package/skills/frontend/state-management-decision-review/references/server-state-caching-and-invalidation.md

@@ -0,0 +1,82 @@
+# Server-State Caching and Invalidation
+
+Use this reference only when reviewing query-key design, invalidation triggers, optimistic-update rollback, or SSR query-client instantiation. Grounded against TanStack Query (`/tanstack/query`) — verify version-sensitive defaults via Context7 before asserting them as the reviewed repo's behavior.
+
+## What people get wrong
+
+The naive story is:
+
+> I fetched the data with `useEffect` + `fetch`, stored it in `useState`, and I refetch when I need fresh data.
+
+That is not a caching strategy — it is ad-hoc state with none of the properties a server-state library provides: deduping concurrent requests for the same key, background revalidation, automatic staleness tracking, or a declarative invalidation surface. Every "it shows old data after I saved" bug report traces back to some version of this pattern, because there is no single place that knows "this data just became stale, refetch it."
+
+The second common wrong assumption:
+
+> Once I switch to a query library, staleness is handled automatically — I don't need to think about invalidation.
+
+Also wrong. The query library gives you the *mechanism* (a keyed cache with a staleness policy); it does not know *when your mutation invalidates which keys* unless you tell it.
+
+## Officially grounded shape
+
+Per current TanStack Query docs (verify against installed major via Context7):
+
+- **`staleTime` defaults to `0`** — a query is considered stale immediately after any successful fetch, meaning it will refetch on next mount/window-focus/reconnect per the active refetch settings. A reviewed repo that never sets `staleTime` and complains about "too many refetches" is fighting the documented default, not a bug in the library.
+- **`refetchOnWindowFocus` defaults to `true`.** If the repo has disabled it, that is a deliberate trade (frequently correct for internal tools with rapidly-changing data; frequently wrong for expensive data that changes rarely) — verify the choice was made intentionally, not accidentally by copying an example.
+- **Query keys are the cache identity.** Two `useQuery` calls with the same key (by deep-equality of the key array) share the same cache entry. This is a feature (dedupes concurrent requests for the same data) but also the most common source of unintended cross-user or cross-context data bleed if a key omits a scoping value (e.g., a user ID, a tenant ID, a locale) that should distinguish two logically different results.
+- **The documented optimistic-update rollback pattern** is: `onMutate` cancels in-flight queries for the affected key(s), snapshots the current cache value via `getQueryData`, writes the optimistic value via `setQueryData`, and returns the snapshot as mutation context; `onError` restores the snapshot from that context via `setQueryData`; `onSettled` invalidates the key(s) to reconcile with the server's actual result regardless of success or failure. All three phases are part of the documented pattern — a mutation with an `onMutate` optimistic write but no `onError` restore is an incomplete implementation of the documented pattern, not a valid variant.
+- **SSR query-client instantiation** must be per-request. Official guidance explicitly warns against creating the `QueryClient` at module/file root level in a server-rendered app ("this also leaks any sensitive data" — because a module-level client is shared across all requests handled by that server process). The documented pattern instead creates the client inside component state (`useState(() => new QueryClient(...))` for the Pages Router / Remix pattern) or a request-scoped factory function that always constructs fresh on the server and memoizes only in the browser (the Server Components pattern).
+
+## Non-negotiable design rules
+
+### 1. Query keys must be fully scoped to what makes the data distinct
+
+If the underlying data differs per user, per tenant, per locale, or per any other dimension, that dimension must appear in the key array. A key like `['orders']` shared across users in a multi-tenant app is a cache-poisoning bug waiting to happen — user B can be shown user A's cached orders if both hit a component using the same key before either fetch resolves distinctly. Prefer `['orders', { userId, ...filters }]`-shaped keys and verify every dimension that changes the response is present.
+
+### 2. Every mutation must name what it invalidates
+
+A mutation with no `onSettled`/`invalidateQueries` call and no direct cache write (`setQueryData`) is a mutation that silently leaves stale data in the cache. Do not accept "the user will probably navigate away and come back, refetching it" as an invalidation strategy — it is not a strategy, it is an accident that happens to often be tolerable.
+
+### 3. Optimistic updates are a three-part contract, not a two-part one
+
+`onMutate` write without `onError` rollback means: user submits an edit, server rejects it (validation failure, conflict, network error), and the UI continues showing the rejected edit indefinitely with no indication anything went wrong. This is a HARD STOP finding per `SKILL.md` — require the `onError` restore before approving.
+
+### 4. SSR query clients are per-request, never a shared singleton
+
+A `const queryClient = new QueryClient()` at module scope in a server-rendered file is a HARD STOP finding — it is not merely a performance smell, it is a mechanism by which one request's fetched data (which may include user-specific or otherwise sensitive data) becomes visible to a subsequent, different user's request handled by the same server process. Verify the client is constructed inside a request-scoped factory or component state, matching the documented pattern for the framework in use (Pages Router, Remix, or Server Components each have a slightly different documented shape — check which applies).
+
+### 5. `staleTime: 0` is a choice, not automatically a bug
+
+Do not flag a query with the default `staleTime` as broken just because it refetches often. First determine whether frequent revalidation is actually correct for that data (rapidly-changing dashboards, real-time-ish lists) before recommending a longer `staleTime`. Recommending `staleTime` increases without confirming the data's actual change frequency is itself a low-confidence finding — label it `inference` and ask, do not assert.
+
+## Minimal safe implementation flow
+
+1. Classify the entity as server state (see `workflow-and-output.md` decision tree).
+2. Design the query key with every scoping dimension the response depends on.
+3. Decide the staleness policy deliberately (default `0`, or an explicit value) based on how often the underlying data actually changes and how costly a stale read is.
+4. Wire every mutation that affects this entity to an explicit invalidation (`onSettled` + `invalidateQueries`) or a direct cache write.
+5. If the mutation is optimistic, implement all three phases: `onMutate` snapshot, `onError` restore, `onSettled` invalidate.
+6. If SSR, confirm the client is constructed per-request, not at module scope.
+
+## High-risk assumptions to kill
+
+- "It'll refetch eventually" — not an invalidation strategy.
+- "The query key doesn't need the user ID, we only have one API base URL" — the key needs to reflect data identity, not URL structure.
+- "Optimistic update without rollback is fine, errors are rare" — the failure mode when it does happen is a UI silently lying to the user about what the server accepted.
+- "One shared QueryClient instance is simpler" — in SSR, simpler and correct are not the same thing here; module-level instantiation is a documented anti-pattern, not a style preference.
+- "Increasing staleTime will fix the re-render complaint" — staleTime affects refetch/staleness, not re-render count; a re-render complaint is a selector/subscription problem (see `client-store-topology-and-rerenders.md`), not a caching-policy problem. Do not conflate the two.
+
+## Safe verification targets
+
+- Grep for `new QueryClient(` and check whether each call site is inside a component/request-scoped function or at module scope.
+- Grep for `useMutation(` and check whether `onMutate` call sites have a matching `onError` that calls `setQueryData` with the snapshot, and an `onSettled` that invalidates.
+- Inspect each `queryKey` array literal for missing scoping dimensions (compare against the fields the associated `queryFn` actually uses to build its request).
+
+## When to push back
+
+Push back if the user asks for:
+
+- a single shared `QueryClient` across all SSR requests "for performance,"
+- an optimistic update shipped without a rollback path "we'll add it later,"
+- a query key without user/tenant scoping "because we'll add multi-tenancy later" — retrofitting scoped keys after data has already leaked across contexts is materially harder than designing them in from the start.
+
+That is not "faster." It is a data-integrity and, in the SSR-singleton case, a data-leak risk.

package/skills/frontend/state-management-decision-review/references/workflow-and-output.md

@@ -0,0 +1,63 @@
+# Review Workflow and Findings Contract
+
+Use this reference for the step-by-step review procedure, the classification decision tree, and the required output shape. Load it for every invocation of this skill; the other two references are conditional on what the classification table surfaces.
+
+## What people get wrong
+
+The common bad assumption is:
+
+> "State management" is one decision — pick a library and put things in it.
+
+That is wrong. It is at least three separate decisions:
+
+1. **classification** — is this entity server-owned, client-owned, or derived?
+2. **caching policy** — for server-owned entities, what is the cache key, the staleness window, and the invalidation trigger?
+3. **topology** — for client-owned entities, how is the store sliced, and what does each consuming component actually subscribe to?
+
+Skipping straight to "which library" without doing step 1 first is how server data ends up duplicated into a client store, or how a single monolithic store becomes the reason every keystroke re-renders unrelated components.
+
+## Step-by-step workflow
+
+1. **Enumerate entities.** List every distinct piece of state touched by the change: each API-fetched resource, each form field, each UI toggle, each computed value. Do not group unrelated entities together — "the todo list" and "the new-todo draft text" are different entities with different lifecycles even though they appear in the same feature.
+2. **Classify each entity** using the decision tree below. Do not skip an entity because it "obviously" belongs somewhere — the point of this skill is that the obvious classification is frequently wrong (see "What people get wrong" above).
+3. **For every server-state entity**, verify:
+   - an explicit query key / cache key exists and is scoped correctly (see `server-state-caching-and-invalidation.md` for scoping detail),
+   - an explicit invalidation trigger exists (a mutation's `onSettled`, a `queryClient.invalidateQueries` call, a documented time-based `staleTime`/polling policy — not "it'll refresh on remount sometimes"),
+   - if the entity is written optimistically, a rollback path exists (`onMutate` snapshot + `onError` restore).
+4. **For every client-state entity**, verify the store slice and selector shape (see `client-store-topology-and-rerenders.md`).
+5. **For every derived-state entity**, verify it is computed on read (selector, `useMemo`, or plain derivation) rather than independently stored and manually kept in sync.
+6. **For SSR applications**, verify the query client and any global store are instantiated per-request, not as a module-level singleton.
+7. **If diagnosing a reported bug or performance complaint**, require concrete evidence before accepting a root cause:
+   - a "stale data" report needs the reproduction sequence (what mutated, what stayed stale, what would have refetched it and didn't),
+   - a "re-render cascade" or "typing lags" report needs profiler evidence (render count or flame-graph excerpt) before any memoization/selector fix is accepted as verified rather than speculative.
+8. **Issue a verdict** with hard stops separated from lower-severity notes, per the output contract below.
+
+## Classification decision tree
+
+```
+Is there a remote/server source of truth for this value?
+├── YES → is it purely computed from other server/client values with no independent write path?
+│   ├── YES → SERVER-DERIVED — must not be independently stored; compute on read
+│   └── NO  → SERVER STATE — must use a cache/query mechanism with an explicit key + invalidation trigger
+└── NO → is it computed entirely from other state already tracked elsewhere (client or server)?
+    ├── YES → CLIENT-DERIVED — must not be independently stored; compute on read (selector/useMemo)
+    └── NO  → CLIENT STATE — session-local; scope it to the narrowest store/slice that needs it
+```
+
+Entities that fail this tree entirely (state with no source, server or computed — e.g., a value the UI invents and never persists or fetches) are a design smell worth naming explicitly, not silently placing in either bucket.
+
+## Findings contract (response minimum, restated with detail)
+
+Every review response from this skill must contain:
+
+1. **Entity classification table** — columns: entity name, classification (server / client / derived), source of truth, current implementation location (file/hook/store). This table is not optional even for a "quick" review; it is the artifact that makes the rest of the review traceable.
+2. **Per server-state entity**: cache key shape, invalidation trigger, rollback path (or "N/A — read-only" / "MISSING — hard stop").
+3. **Per client-store slice touched**: selector shape used by each consumer, and whether any consumer subscribes to more of the store than it reads (a re-render risk).
+4. **Root-cause statement** (bug-diagnosis reviews only) — one of: stale-cache (invalidation trigger missing/wrong), race-condition (out-of-order async writes), re-render-cascade (over-broad subscription/selector), normalization/duplication bug (same fact stored in two places that can diverge). Do not return "state management issue" as a root cause; it is not falsifiable and gives the requester nothing to fix.
+5. **Evidence level** per finding: `repo evidence` (you read the actual code), `documentation-based` (you are asserting a library default/behavior grounded in Context7 or official docs), or `inference` (you are reasoning from incomplete information and it should be verified).
+6. **Verdict**: approve / approve-with-notes / block. HARD STOPS (missing optimistic-update rollback, SSR module-level singleton, PII/auth-token persisted without justification) always force block, listed separately from lower-severity notes.
+7. **Open questions** — anything the review could not resolve from static evidence alone (e.g., "confirm with a profiler trace before merging the memoization fix").
+
+## Version note
+
+TanStack Query and Zustand APIs and defaults are version-sensitive (e.g., `useShallow` import paths have moved across major versions; SSR guidance differs between the Pages Router, Remix, and Server Component patterns). Verify exact API shape and defaults against the repo's installed version and current official docs before asserting a claim as settled fact — see the Context7 Documentation Protocol in `SKILL.md`.