@raishin/vanguard-frontier-agentic 3.0.1 → 3.1.0

package/skills/frontend/react-rsc-data-boundary-review/references/workflow-and-output.md

@@ -0,0 +1,48 @@
+# Review Workflow and Findings Contract
+
+Use this reference for the step-by-step review procedure and the required output shape. Load the other two references only for the specific defect class the RSC code under review actually raises.
+
+## Prerequisites
+
+- Identify the RSC boundary in scope: which files are Server Components (no `'use client'` directive, or files in an RSC-only context such as a Next.js App Router `app/` tree without the directive), which are Client Components (`'use client'` at the top), which files carry a `'use server'` directive (Server Actions/Functions), and which data-access modules are expected to be server-only.
+- Read `package.json` to confirm the framework and version in use (Next.js App Router, a different RSC-capable meta-framework, or plain `react-server-dom-*` wiring) — API names and exact conventions (e.g. `NEXT_PUBLIC_` is Next.js-specific) differ by framework; do not assume a Next.js convention applies to a non-Next.js RSC setup.
+
+## Workflow
+
+1. **Locate every Server Component → Client Component prop boundary.** For each Server Component that renders a Client Component, list every prop passed and trace each value's origin (a literal, an env var, a database/API response field, a full object).
+2. **Enumerate server-only data-access modules.** For each module that reads `process.env`, a database credential, or an internal API token, check whether `import 'server-only'` is the first statement in that file. See `references/boundary-data-leaks-and-taint.md` for the decision tree.
+3. **Check for tainting or narrowing on sensitive values.** For any Server Component that reads a config/response object containing sensitive fields before rendering a Client Component, determine whether the object is narrowed to only non-sensitive fields before being passed as a prop, or whether `experimental_taintUniqueValue` is applied to the sensitive fields upstream.
+4. **Enumerate every `'use server'` function.** For each, check whether a session check (`auth()` or equivalent, tested via a `session?.user` style guard) and — for mutations targeting a specific resource — an ownership check comparing the resource owner to the authenticated user, both execute before any read/write/delete against the data layer. See `references/server-actions-and-env-exposure.md`.
+5. **Enumerate every `'use client'` module that reads `process.env`.** For each environment variable read, confirm the name is prefixed `NEXT_PUBLIC_` (or the framework's equivalent public-env convention); flag any that is not.
+6. **Produce ranked findings** using the output contract below.
+
+## Decision tree
+
+- A Server Component passes a prop to a Client Component whose value traces back to an environment variable, a database credential, an API token, or any other value your review classifies as server-only sensitive → **HIGH** finding, `boundary-data-leak`. Cite React's documented anti-pattern (`documentation-based`).
+- A Server Component passes an entire config/response object (not narrowed to specific non-sensitive fields) to a Client Component, and that object is known or suspected to carry a sensitive field → **HIGH** finding, `taint-boundary-violation`. Note whether `experimental_taintUniqueValue` was available and unused, or whether simple narrowing was the missed opportunity.
+- A prop's value is a plain literal, a non-sensitive string/number, or a field explicitly narrowed out of a larger object (e.g. `config.SERVICE_API_VERSION`) → not a finding.
+- A data-access module reads `process.env`/a credential and has no `import 'server-only'` as its first statement → **HIGH** finding, `missing-server-only-guard`. This holds even if no Client Component currently imports the module — the guard is the structural control against a future accidental import, and its absence is the finding regardless of present-day reachability.
+- A `'use server'` function performs a read/write/delete against the data layer with no session check visible in its body → **HIGH** finding, `action-authz-missing`.
+- A `'use server'` function has a session check but, for a mutation scoped to a specific resource (delete/update by ID), has no ownership check comparing the resource's owner to the authenticated user → **HIGH** finding, `action-authz-missing` (IDOR-shaped gap) — a session check alone proves *someone* is logged in, not that they own the resource being mutated.
+- A `'use client'` module reads a `process.env` variable not prefixed `NEXT_PUBLIC_` → **MEDIUM** finding, `env-exposure-in-client` (the value is `undefined` at runtime in the browser bundle, and the read itself signals a broken mental model of the boundary that may mask a worse leak elsewhere).
+- A `'use client'` module reads only `NEXT_PUBLIC_`-prefixed variables → not a finding.
+
+## Output contract
+
+Every response from this skill must return:
+
+1. **Scope** — the Server Component(s), Client Component prop boundaries, `'use server'` action(s), and/or `'use client'` module(s) reviewed.
+2. **Ranked findings** — each with file:line, defect category (`boundary-data-leak` / `missing-server-only-guard` / `action-authz-missing` / `env-exposure-in-client` / `taint-boundary-violation`), the concrete data-flow trace (naming every hop from the sensitive value's origin to the boundary crossing or missing guard), and a fix sketch matching React's or Next.js's documented pattern.
+3. **Guard status per finding** — an explicit statement of whether `server-only`, `experimental_taintUniqueValue`, or a session/ownership check is present on the traced path; never infer one exists elsewhere in the codebase.
+4. **Evidence level per finding** — `repo evidence`, `documentation-based`, or `structural-risk`. Label structural risk findings as structural risk explicitly — do not imply confirmed exploitation without live evidence (e.g., a captured network payload showing the secret in the client bundle).
+5. **Verdict** — approve / approve-with-notes / block.
+6. **Open questions or out-of-scope items** — e.g., "confirming the secret actually reached a browser requires live request/network interception, not static review," or "this file also has a client-side XSS-shaped concern unrelated to the RSC boundary — out of scope for this skill, recommend `frontend-dom-xss-csp-review`."
+
+## When to push back
+
+Push back if the user asks to:
+
+- approve a prop pass because "the Client Component doesn't actually use that field" — an unused sensitive prop still serializes into the client payload; unused-in-render is not the same as never-transmitted,
+- treat a `server-only` import anywhere in the project as covering a different file that itself reads the sensitive value with no guard of its own,
+- skip the ownership check on a `'use server'` mutation because "the session check already runs" — a session check proves authentication, not authorization over the specific resource being mutated,
+- downgrade an untraced whole-object prop pass to informational because "the object probably doesn't have anything sensitive in it" — trace the object's actual shape before clearing it, or state explicitly that the shape could not be confirmed.

package/skills/frontend/react-state-effects-review/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: react-state-effects-review
+description: Statically review useState/useEffect/useReducer call sites against React's documented "You Might Not Need an Effect" anti-pattern catalog, plus race-condition and stale-closure detection via dependency-array and cleanup-function analysis, producing ranked file:line findings.
+allowed-tools: Read Grep Glob
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-07-02"
+  category: architecture
+---
+
+# React State & Effects Review
+
+## Purpose
+
+Review `useState`, `useEffect`, and `useReducer` call sites for the specific defect classes React's own documentation calls out — effects that should be render-time computations or event-handler logic, missing cleanup/cancellation guards on async effects, and stale closures caused by dependency-array mistakes — without re-litigating component decomposition, styling, or live performance profiling in every response. This skill exists so those adjacent concerns stay out of scope and the review stays focused on the documented anti-pattern catalog plus race-condition and stale-closure evidence.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- review a component that uses `useEffect`, `useState`, or `useReducer` before merge,
+- diagnose a bug consistent with a race condition (stale data flashes onto the screen, results from a previous request overwrite a later one),
+- diagnose an "infinite render loop" or "effect fires too often" report,
+- decide whether a given effect is necessary at all.
+
+Do not use this skill for:
+
+- class-component lifecycle methods (`componentDidMount`, `componentDidUpdate`, `componentWillUnmount`) — different API surface; use a general React review instead,
+- a bug that requires live reproduction (browser DevTools profiling, network-tab timing) to confirm — hand off to a runtime tool; static analysis can only identify the missing guard, not prove the bug fired in production,
+- component decomposition, prop-interface, or context-usage review — that is `react-component-architecture-review`.
+
+## Context7 Documentation Protocol
+
+- Resolve the React library ID with `resolve-library-id` (matched result: `/reactjs/react.dev`) before labeling any specific pattern as an anti-pattern.
+- Before citing "You Might Not Need an Effect" guidance, call `query-docs` for the exact pattern in question (e.g., "adjusting state on prop change", "resetting state with a key") — do not assert the anti-pattern classification from memory, and do not assume every effect matches the catalog without checking which entry actually applies.
+- Read `package.json` first to confirm the installed React major version. `useEffectEvent` (stable in React 19.2) is the documented fix for a specific class of stale-closure problem; if the repo is on an older major, that specific fix is unavailable and the finding must recommend the pre-19.2 pattern (ref/callback ref, or accepting the value as a dependency) instead.
+- If the repo uses the React Compiler, verify current compiler-specific guidance via `query-docs` before assuming manual dependency-array reasoning is unchanged — do not assume compiler-driven memoization rules automatically apply to hand-authored effects.
+- If Context7 is unavailable, fall back to the `official_docs` URLs in this skill's `metadata.json` and label the claim `documentation-based, unverified against current release`.
+
+## Lean operating rules
+
+- First read `package.json` to confirm the installed React major and whether `useEffectEvent` is available before recommending it as a fix.
+- For every effect in scope, classify it before evaluating it: (a) synchronizing with an external system (valid effect usage per docs), (b) adjusting/resetting state in response to props or other state with no external system involved (the documented anti-pattern — compute during render or reset via `key` instead), or (c) event-handler logic misplaced in an effect (should run in the handler that caused it, not react to a state change). Do not apply one verdict to all effects uniformly.
+- For every async effect that sets state from a promise/callback result, require an explicit cancellation guard (an `ignore` flag checked before the state update, or an `AbortController`). Its absence is a race-condition finding, not a style note — describe the concrete input sequence that triggers stale data (e.g., "slow request for user A resolves after the fast request for user B, overwriting B's data with A's").
+- For every dependency array, check each value read inside the effect body against the array. A missing dependency is only a non-issue when the omitted value is provably stable (a `setState` function, a `dispatch` function, a `ref.current` read inside the effect, or a value wrapped in `useEffectEvent` where the repo's React version supports it) — otherwise it is a stale-closure finding.
+- Do not fabricate a race condition or stale-closure claim without describing the exact trigger sequence (what user action, what timing, what state transition). A finding that only says "this could be a race condition" without the sequence is not a valid finding.
+- Treat effects that intentionally run once for genuine one-time external-system setup (subscribing to a widget, initializing a non-React library) as valid; do not flag the empty dependency array itself as a defect — flag only if the effect body also reads reactive values it omits.
+- Never execute, build, or run application code as part of this review; this is a static-review skill (Read/Grep/Glob only).
+- Flag any effect that performs an authenticated write or other state-mutating network call without an idempotency guard or cancellation guard as a HIGH-severity finding — a race condition here risks duplicate financial or state-changing operations, not just a UI glitch.
+
+## 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 anti-pattern decision tree, and the required output shape.
+- [Effect cleanup and race conditions](references/effect-cleanup-and-race-conditions.md) — load only when reviewing an async effect (data fetching, subscriptions, timers) for cancellation/cleanup correctness.
+- [Stale closures and dependency arrays](references/stale-closures-and-dependency-arrays.md) — load only when a dependency-array omission or stale-closure suspicion is present.
+
+## Response minimum
+
+Return, at minimum:
+
+- the component(s), files, and specific hook call sites in scope,
+- ranked findings with file:line evidence, anti-pattern category (per the docs catalog), and a concrete fix sketch matching the docs' recommended alternative,
+- for every race-condition finding, the concrete trigger sequence and the missing guard,
+- evidence level per finding (`repo evidence`, `documentation-based`, or `inference`),
+- verdict (approve / approve-with-notes / block),
+- open questions or scope the review could not cover (e.g., "requires live reproduction to confirm timing" for suspected but unconfirmed races).

package/skills/frontend/react-state-effects-review/metadata.json

@@ -0,0 +1,27 @@
+{
+  "id": "react-state-effects-review",
+  "name": "React State & Effects Review",
+  "type": "skill",
+  "provider": "frontend",
+  "harnesses": [
+    "claude-code",
+    "cursor",
+    "codex",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Reviews useState/useEffect/useReducer usage for the documented anti-patterns (unneeded effects, missing cleanup, race conditions, stale closures), classifying each effect against React's own 'You Might Not Need an Effect' catalog and grounding every claim via Context7 against the repo's confirmed React version.",
+  "source_type": "original",
+  "official_docs": [
+    "https://react.dev/learn/you-might-not-need-an-effect",
+    "https://react.dev/learn/synchronizing-with-effects",
+    "https://react.dev/reference/react/useEffect",
+    "https://react.dev/learn/removing-effect-dependencies"
+  ],
+  "security_notes": "Static-review-only skill: it reads and greps component source but never executes, builds, or runs application code. Flag effects that perform authenticated writes (mutations) without idempotency/cancellation guards — a race condition here can cause duplicate financial or state-changing operations, not just a UI bug — as a HIGH-severity finding requiring immediate escalation, not a style note.",
+  "last_verified": "2026-07-02",
+  "path": "skills/frontend/react-state-effects-review",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/frontend/react-state-effects-review/references/effect-cleanup-and-race-conditions.md

@@ -0,0 +1,89 @@
+# Effect Cleanup and Race Conditions
+
+Use this reference only when the effect under review is asynchronous — it fetches data, opens a connection, subscribes to a stream, or sets a timer — and you need to verify the cleanup/cancellation guard is correct.
+
+## What people get wrong
+
+The common bad assumption is:
+
+> "The effect updates state when the promise resolves, so it's correct."
+
+That is incomplete. React does not cancel in-flight promises when an effect re-runs or the component unmounts. If a slow request from an earlier render resolves *after* a faster request from a later render, the stale result can overwrite the fresh one unless the effect explicitly guards against it. This is the documented root cause of "data flashes to a previous value when switching quickly."
+
+## Officially grounded pattern
+
+React's own docs (`you-might-not-need-an-effect.md`, `synchronizing-with-effects.md`, and the `useEffect` reference) all converge on the same shape for fetch effects: a boolean `ignore` flag set in the cleanup function, checked before every state update derived from the async result.
+
+```js
+function SearchResults({ query }) {
+  const [results, setResults] = useState([]);
+  const [page, setPage] = useState(1);
+  useEffect(() => {
+    let ignore = false;
+    fetchResults(query, page).then(json => {
+      if (!ignore) {
+        setResults(json);
+      }
+    });
+    return () => {
+      ignore = true;
+    };
+  }, [query, page]);
+  // ...
+}
+```
+
+The same pattern applies with `async`/`await` syntax — declare `ignore` outside the async function, check it after the `await`, and return the cleanup function that flips it:
+
+```js
+useEffect(() => {
+  let ignore = false;
+
+  async function startFetching() {
+    const json = await fetchTodos(userId);
+    if (!ignore) {
+      setTodos(json);
+    }
+  }
+
+  startFetching();
+
+  return () => {
+    ignore = true;
+  };
+}, [userId]);
+```
+
+`AbortController` is an equally valid, and more resource-efficient, variant when the underlying request API supports cancellation (most `fetch`-based clients do) — it actually cancels the network request instead of only ignoring its result. Prefer it when the codebase already has an established `AbortController` convention; do not introduce it as a novel pattern in a codebase that consistently uses the `ignore`-flag convention without a reason tied to the specific finding (e.g., an expensive request that should genuinely be aborted, not just ignored).
+
+## Non-negotiable design rules
+
+1. **Every async effect that calls `setState` from a resolved promise or callback must have a guard.** No exceptions for "it's unlikely to race in practice" — the trigger sequence (fast navigation, fast re-render, flaky network) is exactly the kind of intermittent, hard-to-reproduce condition that is expensive to debug once it reaches production. Treat the absence of a guard as a finding regardless of how unlikely the reviewer judges the race to be.
+2. **The guard must be checked immediately before every state update inside the async chain**, not just the first one. An effect that fetches and then makes a second dependent call must check `ignore` (or `signal.aborted`) before each `setState`, not only the first.
+3. **`StrictMode` double-invocation in development is not the same bug as a production race condition.** `StrictMode` runs setup → cleanup → setup once, synchronously, specifically to verify that the cleanup function correctly undoes the setup. If an effect breaks under `StrictMode` double-invocation, that is evidence the cleanup is incomplete or missing — it is not a `StrictMode`-only artifact to work around by disabling `StrictMode`. Do not recommend removing `StrictMode` as a fix for a broken cleanup function.
+4. **A `setTimeout`/`setInterval`-based effect needs `clearTimeout`/`clearInterval` in its cleanup**, and a subscription-based effect needs the corresponding unsubscribe/disconnect call — the same guard-in-cleanup principle applies beyond fetch. Treat a missing `clearInterval`/unsubscribe as the same severity class as a missing `ignore` flag: it is a resource leak and, if the interval body calls `setState`, a potential update-on-unmounted-component or stale-closure bug.
+
+## Severity escalation
+
+Treat a missing cancellation guard as **HIGH severity, not MEDIUM**, when the async effect's resolution triggers:
+
+- an authenticated write, mutation, or other state-changing network call (duplicate submission risk, not just a stale read),
+- a redirect, navigation, or auth-state change (wrong-user data exposure risk),
+- a write to a shared/global store rather than local component state (blast radius extends beyond the component).
+
+Otherwise (a stale read into local UI state with no side effect beyond a flicker), MEDIUM is appropriate — still a real bug, but not a data-integrity or security risk.
+
+## Verification targets
+
+When repo evidence is available, verify the finding against:
+
+- the actual async function signature — does it accept or already use an `AbortSignal`? If yes and the effect ignores it, that is a stronger finding (cancellation capability exists and is unused) than the case where no cancellation mechanism exists at all.
+- whether the dependency array includes every reactive value used to construct the request (query, page, userId in the examples above) — a missing request-parameter dependency is a *different* finding (stale closure, see the dependency-array reference) that often co-occurs with a missing cleanup guard in the same effect.
+
+## When to push back
+
+Push back if the user asks to:
+
+- "just add a loading spinner" as the fix for a reported race condition — a spinner does not prevent stale data from overwriting fresh data; it only hides the timing, it does not fix it,
+- suppress the exhaustive-deps lint warning on an async effect instead of adding the guard — the warning is frequently the signal that led to finding the missing guard in the first place,
+- disable `StrictMode` to make a race condition symptom disappear in development instead of fixing the missing cleanup — this hides the bug in dev while leaving it live in production.

package/skills/frontend/react-state-effects-review/references/stale-closures-and-dependency-arrays.md

@@ -0,0 +1,74 @@
+# Stale Closures and Dependency Arrays
+
+Use this reference only when a dependency-array omission or a stale-closure suspicion is present — a value is read inside an effect body but is missing from (or wrongly present in) the dependency array.
+
+## What people get wrong
+
+The common bad assumption is:
+
+> "The effect's dependency array is a performance knob — trim it to reduce re-runs."
+
+That is backwards. The dependency array is not a performance setting; it is a correctness contract. Every reactive value (props, state, and anything derived from them) that the effect body reads must be listed, or the effect closes over a stale value from the render in which it was created and keeps using that stale value until something else happens to cause a re-run. This is the documented root cause of "the effect uses an old value even though the state clearly updated."
+
+## Officially grounded pattern: distinguishing stable from reactive values
+
+Not every value used inside an effect is "reactive" in the sense that omitting it is a bug:
+
+- **Provably stable, safe to omit:** the `setState` function returned by `useState`, the `dispatch` function returned by `useReducer`, and `ref.current` reads performed *inside* the effect body (refs themselves are not reactive; React guarantees `set` function identity is stable across renders).
+- **Reactive, must be included if read:** any prop, any state variable, any value derived from props/state (including objects and functions recreated on every render, e.g., an inline object literal or arrow function passed as a prop).
+- **Non-reactive but currently forces a re-run because it's a function/object identity that changes every render:** this is the actual problem `useEffectEvent` was designed to solve (see below) — the value is logically "the latest one," not something the effect should resynchronize over.
+
+## Non-negotiable design rules
+
+1. **Do not classify a missing dependency as "intentional" without evidence.** A dependency array that omits a value read in the effect body is a stale-closure finding by default. It is only safe when the omitted value is one of the provably-stable categories above, or the codebase has already isolated the non-reactive read into a mechanism designed for that purpose (see rule 3). "The author probably meant to do that" is not evidence.
+2. **A dependency-array lint suppression (`// eslint-disable-next-line react-hooks/exhaustive-deps`) is itself a finding**, not a signal that the array is correct. Read the suppressed line and independently verify whether the omission is safe using rule 1's criteria.
+3. **When the React version supports `useEffectEvent`** (stable as of React 19.2; confirm via `package.json` and Context7 before assuming availability), it is the documented mechanism for reading the *latest* value of a prop or state variable inside an effect without making that value reactive. Example from the docs — `onMessage` needs the current `isMuted` value without forcing the connection effect to re-run every time `isMuted` toggles:
+
+   ```js
+   function ChatRoom({ roomId }) {
+     const [messages, setMessages] = useState([]);
+     const [isMuted, setIsMuted] = useState(false);
+
+     const onMessage = useEffectEvent(receivedMessage => {
+       setMessages(msgs => [...msgs, receivedMessage]);
+       if (!isMuted) {
+         playSound();
+       }
+     });
+
+     useEffect(() => {
+       const connection = createConnection();
+       connection.connect();
+       connection.on('message', (receivedMessage) => {
+         onMessage(receivedMessage);
+       });
+       return () => connection.disconnect();
+     }, [roomId]); // ✅ All dependencies declared
+   }
+   ```
+
+   The Effect Event itself (`onMessage`) is **not** reactive and must be omitted from the effect's dependency array — only `roomId` remains, because `roomId` is the value that should actually trigger resynchronization (reconnecting).
+4. **On React versions without `useEffectEvent`**, do not recommend it. The pre-19.2 alternatives are: accept the value as a real dependency (and accept the effect re-running when it changes, if that is actually correct behavior), or store the latest value in a `ref` updated on every render and read `ref.current` inside the effect (a manual, documented workaround with the same intent but without the ergonomics or the "must be called during render" constraint of `useEffectEvent`). State which alternative applies and why the effect's actual resynchronization need (or lack thereof) supports it.
+5. **A stale closure over a `setState` value called without the updater form is a separate, related finding.** `setCount(count + 1)` inside a callback that closes over an old `count` is a stale-closure bug even outside effects; inside an effect or an effect-scheduled callback, prefer the updater form `setCount(c => c + 1)` when the new value only depends on the previous value — this sidesteps the staleness question entirely rather than requiring the value to be a correct dependency.
+
+## Adversarial checklist
+
+Before accepting a dependency-array omission as safe, answer:
+
+- Is the omitted value actually read inside the effect body, or only inside a nested function that is *not* called synchronously within the effect (e.g., only referenced in a comment or dead code)? If it's genuinely unread, there is no finding.
+- Is the omitted value one of the provably-stable categories (setState/dispatch function, `ref.current`)? If not, is there a `useEffectEvent` wrapper already isolating it, and does the target React version actually support `useEffectEvent`?
+- If the value were included as a real dependency, would the effect's re-run behavior actually be wrong (e.g., reconnecting a socket every time an unrelated piece of state changes)? If re-running is actually correct and just looks noisy, the fix is not to omit the dependency — it may be to reconsider whether that value belongs in the same effect at all.
+- Does the effect call an inline object or array literal as a dependency (e.g., `[{ id: props.id }]`)? A new object identity is created every render, so this dependency is present but still causes the effect to re-run every render — a different but related finding: the fix is to depend on the primitive fields (`props.id`) instead of the object.
+
+## Verification targets
+
+- Confirm the installed React major (`package.json`) before citing `useEffectEvent` as available — it is a documented, comparatively recent addition (React 19.2). Repos on 18.x or earlier need the `ref`-based workaround instead.
+- Cross-reference any stale-closure finding in an async effect against `effect-cleanup-and-race-conditions.md` — a missing request-parameter dependency (e.g., `page` omitted from a fetch effect's array) is often paired with a missing cancellation guard in the same effect, and both should be reported together as related findings, not two disconnected line items.
+
+## When to push back
+
+Push back if the user says:
+
+- "just disable the lint rule" as the resolution for a stale-closure finding — the rule exists specifically to catch this class of bug; disabling it removes the signal without fixing the defect,
+- "the value rarely changes so it's fine to omit" — "rarely" is not "never"; the bug still exists and will surface intermittently, which is the expensive-to-debug failure mode this skill exists to catch pre-merge,
+- "add `// eslint-disable` everywhere this warns" as a blanket policy — each suppression must be independently verified per the adversarial checklist above, not applied wholesale.

package/skills/frontend/react-state-effects-review/references/workflow-and-output.md

@@ -0,0 +1,46 @@
+# Review Workflow and Findings Contract
+
+Use this reference for the step-by-step procedure, the anti-pattern decision tree, and the required output shape. Load the other two references (`effect-cleanup-and-race-conditions.md`, `stale-closures-and-dependency-arrays.md`) only when the step below tells you to.
+
+## Workflow
+
+1. **Inventory.** List every `useState`, `useEffect`, `useReducer`, and `useLayoutEffect` call site in scope, with file:line. Do not skip `useLayoutEffect` — it is not interchangeable with `useEffect`; it exists specifically for layout measurement that must happen before the browser paints, so a "convert to useEffect" recommendation is wrong unless you have confirmed the effect does not read layout geometry.
+2. **Classify each effect** using the decision tree below. This step decides which reference (if any) to load next.
+3. **For effects classified as "synchronizing with an external system" that are async** (fetch, subscription callback, timer), load `effect-cleanup-and-race-conditions.md` and verify a cancellation guard exists.
+4. **For any effect with an object, function, or derived-value dependency**, or any effect where a value used in the body is missing from the dependency array, load `stale-closures-and-dependency-arrays.md` and verify the omission is provably safe.
+5. **Produce ranked findings** using the output contract below. Rank HIGH (race condition on authenticated writes, or a confirmed anti-pattern causing an infinite loop) above MEDIUM (documented anti-pattern with no loop/data-corruption risk) above LOW (style/clarity).
+
+## Anti-pattern decision tree
+
+For each effect, ask in order:
+
+1. **Does this effect synchronize with something outside React** (a DOM API, a browser API like the window title, a subscription to a non-React widget, a network connection, `localStorage`)?
+   - **Yes** → this is valid effect usage per `synchronizing-with-effects`. Proceed to step 2 below (async/cleanup check) if it is asynchronous. Do not flag the effect's existence as a defect.
+   - **No** → continue to question 2.
+2. **Does the effect only call `setState` with a value derived from props or other state, with no external system involved?**
+   - **Yes, and the derived value can be computed inline during render** → this is the documented "Adjusting state on prop change in an Effect" or "Adjusting some state when a prop changes" anti-pattern. Fix: compute the value during render instead of storing it in a second `useState` synchronized by an effect. If the current render's derived value depends on the *previous* render's props (e.g., resetting a selection when a list changes), prefer storing an `ID` and comparing it inline during render over an effect.
+   - **Yes, and the goal is resetting all state when an identity-like prop changes** (e.g., `userId`, `itemId`) → this is the documented "Resetting state with an Effect" anti-pattern. Fix: pass the identity value as the `key` prop on the component (or a wrapped inner component) so React remounts and resets state automatically, instead of an effect that calls `setState(initialValue)`.
+   - **No** → continue to question 3.
+3. **Does the effect run logic that should only happen in response to a specific user action** (a click, a form submission) rather than in response to a state/prop change?
+   - **Yes** → this is the documented "event-handler logic misplaced in an effect" anti-pattern (e.g., sending an analytics event or a mutation inside an effect that fires whenever some state changes, instead of inside the handler that caused the change). Fix: move the logic into the event handler. If the same logic must run regardless of which handler triggered the state change, that is one of the few legitimate reasons to keep it in an effect — but confirm that is actually true before accepting it as an exception.
+   - **No** → continue to question 4.
+4. **Does the effect exist solely to run initialization logic once on mount** (e.g., `loadDataFromLocalStorage()`, `checkAuthToken()`) at the top level of `App`?
+   - **Yes** → flag it. In development with `StrictMode`, this class of effect runs twice, which is documented as an intentional signal that the logic was not designed to be resilient to remount. Fix depends on the actual intent: module-level code that should run once per page load (not per component mount) usually does not belong in an effect at all; if it must be effect-based and idempotency truly cannot be achieved, a `useRef` guard (`if (ranOnce.current) return; ranOnce.current = true;`) is the documented workaround, not a first choice.
+
+Do not stop at the first "yes" in isolation without checking file:line evidence — cite the exact code that establishes the classification.
+
+## Output contract
+
+Every response must return:
+
+1. **Scope** — the component(s), files, and hook call sites reviewed (file:line for each).
+2. **Evidence level** — per finding: `repo evidence` (cited file:line), `documentation-based` (cites the specific react.dev page/section via Context7), or `inference` (a plausible but unconfirmed race/loop that needs live reproduction to prove).
+3. **Ranked findings** — for each: anti-pattern category (one of the four decision-tree branches, or "missing cleanup guard", or "stale closure"), file:line, the concrete trigger sequence for any race/loop claim, and a fix sketch that matches the docs' recommended alternative (not a generic "add a check" — name the actual pattern: compute during render, reset via `key`, move to handler, add `ignore` flag/`AbortController`, add missing dependency, or `useEffectEvent` if the React version supports it).
+4. **Verdict** — `approve`, `approve-with-notes`, or `block`. Block only for HIGH-severity findings (confirmed infinite loop, or a race condition on an authenticated write/mutation).
+5. **Open questions** — anything requiring live reproduction (network timing, StrictMode remount behavior in the target environment) that static review cannot confirm; state this explicitly rather than asserting a bug "will occur" without evidence of the trigger sequence.
+
+## Hard stops
+
+- Do not recommend removing an effect that genuinely synchronizes with an external system. That is valid effect usage per docs, not an anti-pattern — removing it breaks the synchronization.
+- Do not flag every `useEffect` call site as suspicious by default. Each finding must map to a specific decision-tree branch with file:line evidence.
+- Do not claim a race condition "will occur" without describing the concrete input sequence (which two operations race, in what order, and what the observable symptom is).

package/skills/frontend/routing-navigation-review/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: routing-navigation-review
+description: Reviews route-tree structure, loader/action placement, code-splitting boundaries, and navigation-blocking/focus-management behavior in React Router and Next.js applications for correctness, server-side security enforcement, and accessibility conformance on route transitions.
+allowed-tools: Read Grep Glob
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-07-02"
+  category: architecture
+---
+
+# Routing & Navigation Review
+
+## Purpose
+
+Review a frontend application's route tree — path/layout nesting, loader/action data-fetching placement, code-splitting boundaries, and navigation-blocking/focus-management behavior — without re-litigating what data a loader fetches from the backend contract (that is `api-integration-contract-review`) or SSR streaming/hydration mechanics at a route's data boundary (that is `ssr-hydration-streaming-diagnosis`) in every response. This skill exists because route-level defects hide in three distinct, easily-conflated places: a route that is "protected" only by hiding a nav link or redirecting client-side (an authorization bypass reachable by typing the URL directly), a code-split boundary that accidentally serializes loader→component→action instead of loading them in parallel, and a route transition that silently drops keyboard focus with no status announcement (a WCAG 2.4.3 / 4.1.3 failure that is invisible unless you trace it deliberately).
+
+## When to use
+
+Use this skill when the user asks to:
+
+- review a new route or a route-tree restructuring before merge,
+- audit whether routes described as "protected" are actually enforced server-side, not just hidden client-side,
+- investigate broken deep-links, lost filter/pagination/tab state on refresh, or "back button doesn't work right" bugs,
+- respond to an accessibility audit finding of lost focus or missing status announcements on navigation,
+- review code-splitting/lazy-loading changes to a route tree for waterfall regressions.
+
+Do not use this skill for:
+
+- reviewing what data a loader fetches from the backend contract, response shape, or error handling — use `api-integration-contract-review` instead,
+- SSR streaming/hydration mechanics at a route's data boundary (Suspense boundaries, streaming HTML, hydration mismatches) — use `ssr-hydration-streaming-diagnosis` instead,
+- component-internal state with no route/URL involvement.
+
+## Context7 Documentation Protocol
+
+- Resolve library IDs before citing any framework-specific claim: `/remix-run/react-router` for React Router, `/vercel/next.js` for Next.js. Do not assume API shape from memory — both frameworks' routing/data APIs have changed materially across major versions (React Router v6 object-route API vs. v7 framework-mode route modules; Next.js Pages Router vs. App Router).
+- Before asserting server-side enforcement patterns in React Router, query `/remix-run/react-router` for "loader authentication redirect" and confirm the current guidance: a `loader` (or a middleware paired with a `loader` to force it to run on every client-side navigation) is the enforcement point — a component-level redirect or conditional render is not, because React Router still renders/matches the route client-side without a network round trip that a server can gate.
+- Before asserting server-side enforcement patterns in Next.js, query `/vercel/next.js` for "data access layer authorization" and confirm the current guidance: official docs explicitly frame `middleware`/proxy-based checks (cookie-presence checks run at the edge) as an *optimistic* first pass for UX/redirect purposes, and require the actual authorization check to live in a server-only Data Access Layer close to the data source (Server Component, Server Action, or Route Handler) — do not treat a middleware matcher as sufficient enforcement on its own.
+- Before asserting code-splitting behavior, query `/remix-run/react-router` for "lazy route module" and confirm current guidance: the recommended `lazy` route property loads the component and its `loader`/`action` together (e.g., via `Promise.all`) so they resolve in parallel — a common regression is `await`-ing them in sequence instead.
+- Before asserting navigation-blocking behavior, query `/remix-run/react-router` for "useBlocker" and confirm current constraints: `useBlocker` only works within data routers (`createBrowserRouter`/framework mode) and explicitly does not intercept hard reloads or cross-origin navigations — do not present it as a universal unsaved-changes guard.
+- Verify the installed major version of React Router or Next.js (`package.json`) before asserting version-specific route-module or App Router conventions; if the repo is on Pages Router or React Router v5/v6 classic mode, framework-mode/App Router guidance does not transfer directly.
+- If Context7 is unavailable, fall back to the `official_docs` URLs in this skill's `metadata.json` and label the claim `documentation-based, unverified against current release`.
+
+## Lean operating rules
+
+- First map the full route tree (paths, layout nesting, index routes) before evaluating any individual route — a route's effective protection or focus behavior can depend on a parent layout's loader or wrapper.
+- Classify every route as public or protected using the authorization model the team actually has, not assumption. A route is protected only if there is a server-side enforcement point: a React Router `loader` (or middleware forced to run via a paired loader) that redirects/throws, or a Next.js Data Access Layer check inside a Server Component/Server Action/Route Handler. Hiding a nav link, a client-side `useEffect` redirect, or a component-level conditional render is UX affordance only — treat any "protected" route lacking a paired server-side enforcement point as a blocking (HIGH) security finding, not a style note.
+- Do not accept a Next.js `middleware`/proxy auth check as sufficient enforcement by itself; official Next.js guidance frames it as an optimistic edge check. Require the corresponding Data Access Layer check to also exist, and flag a middleware-only implementation as a HIGH finding even if the middleware matcher looks correct.
+- When reviewing code-splitting, verify whether loader/component/action for a lazy route resolve via a parallel construct (e.g., `Promise.all`, or the framework's single `lazy` property that loads them together) versus sequential `await` calls that create a waterfall — the latter is a measurable performance regression, not a style preference.
+- Treat any view-critical state (active filter, pagination page, selected tab, search query) that lives only in component state/memory as a defect if it should be shareable or survive a refresh — it belongs in the URL (path segment or search params), not only in memory. This is what breaks deep-links and the back button.
+- Trace focus management on every route transition: identify what receives focus after navigation (a heading, the main landmark, or nothing) and whether an `aria-live` region announces the route/status change for assistive technology. Absence of either is an accessibility (WCAG 2.4.3 Focus Order / 4.1.3 Status Messages) finding, not a nice-to-have.
+- For form-heavy routes, verify navigation-blocking (e.g., React Router `useBlocker`) exists for unsaved changes, and verify its known limits (SPA-only; does not cover hard reloads or cross-origin navigation) are either accepted knowingly or covered by a `beforeunload` handler for the hard-reload case.
+- Never execute, build, or run application code as part of this review; this is a static-review skill (Read/Grep/Glob only). Do not attempt to open a browser or simulate navigation to "check" focus behavior — trace it from source (component refs, `useEffect` on location change, `aria-live` regions) and label the finding `repo evidence` with a caveat that runtime confirmation was not performed.
+
+## 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 route-tree mapping table, and the required output shape.
+- [Server-side enforcement patterns](references/server-enforcement-patterns.md) — load only when auditing whether a "protected" route has real server-side enforcement (React Router loader/middleware, Next.js Data Access Layer) versus client-side-only gating.
+- [Code-splitting and URL state](references/code-splitting-and-url-state.md) — load only when reviewing lazy-loading/waterfall regressions or when view-critical state needs to move into the URL.
+- [Focus management and navigation blocking](references/focus-and-navigation-blocking.md) — load only when reviewing focus/`aria-live` behavior on route transitions or unsaved-changes navigation blocking.
+
+## Response minimum
+
+Return, at minimum:
+
+- a route-tree table: path, protection level with its server-side enforcement pointer (or "none found"), code-split boundary, and focus-management target,
+- ranked findings with file:line evidence,
+- evidence level per finding (`repo evidence`, `documentation-based`, or `inference`),
+- verdict (approve / approve-with-notes / block),
+- open questions or scope the review could not cover (e.g., runtime focus behavior not simulated, transitive import not read).

package/skills/frontend/routing-navigation-review/metadata.json

@@ -0,0 +1,27 @@
+{
+  "id": "routing-navigation-review",
+  "name": "Routing & Navigation Review",
+  "type": "skill",
+  "provider": "frontend",
+  "harnesses": [
+    "claude-code",
+    "cursor",
+    "codex",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Reviews route-tree structure, loader/action placement, code-splitting, and navigation-blocking/focus-management for correctness, security enforcement, and accessibility conformance.",
+  "source_type": "original",
+  "official_docs": [
+    "https://reactrouter.com/start/framework/route-module",
+    "https://reactrouter.com/start/data/actions",
+    "https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes",
+    "https://www.w3.org/WAI/ARIA/apg/patterns/"
+  ],
+  "security_notes": "Client-side-only route guards (hiding a nav link, redirecting in a component) are UX only; treat any route lacking a paired server-side enforcement point (loader auth check, middleware, or BFF authorization) as a blocking security finding. Static-review-only skill: it reads and greps route source but never executes, builds, or runs application code.",
+  "last_verified": "2026-07-02",
+  "path": "skills/frontend/routing-navigation-review",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/frontend/routing-navigation-review/references/code-splitting-and-url-state.md

@@ -0,0 +1,72 @@
+# Code-Splitting and URL State
+
+Use this reference only when reviewing lazy-loading/waterfall regressions in a route tree, or when view-critical state needs to move into the URL. Load it during steps 4–5 of the review workflow.
+
+## What people get wrong
+
+The naive assumption is:
+
+> "I added `lazy: () => import('./route')`, so the route is code-split correctly."
+
+That covers the component, but a route module also has a `loader` and possibly an `action`. If those are fetched with separate sequential `await` statements instead of a combined parallel construct, the route now pays for two or three round trips (component chunk, then loader chunk, then action chunk) instead of one — a self-inflicted waterfall that looks identical in the diff ("we added lazy loading!") but regresses time-to-interactive.
+
+A second common assumption:
+
+> "The filter/tab/page state is in `useState`, so it works fine — I can see it update."
+
+It "works" for the current session in the current tab. It does not survive a refresh, cannot be shared as a link, and breaks the browser back/forward button's expected behavior — all silent failures that only surface as user complaints ("I sent my coworker this link and it didn't have my filters").
+
+## Officially grounded code-splitting shape (React Router)
+
+- The recommended `lazy` route property loads the component and its data functions together. The documented pattern uses `Promise.all` (or the single combined `lazy` module import) specifically so the component and `loader` resolve **in parallel**, not one after another:
+
+```tsx
+{
+  path: "/app",
+  lazy: async () => {
+    // load component and loader in parallel before rendering
+    const [Component, loader] = await Promise.all([
+      import("./app"),
+      import("./app-loader"),
+    ]);
+    return { Component, loader };
+  },
+}
+```
+
+- The simpler single-module `lazy: () => import("./about")` form (importing one module that exports `loader`/`action`/`Component` together) achieves the same parallelism implicitly, because it's one dynamic import resolving one module graph.
+- A regression to watch for: someone splits `loader`, `action`, and `Component` into three separate `lazy.loader`, `lazy.action`, `lazy.Component` async functions (a valid, documented granular form) but then has one `await` the result of another inside its own function body instead of letting the router resolve them independently — that reintroduces a sequential dependency the granular form was supposed to avoid.
+
+## Officially grounded code-splitting shape (Next.js)
+
+- Next.js App Router code-splits by route segment automatically; the equivalent regression to check for is a route's `page.tsx` or `layout.tsx` performing sequential `await` calls for independent data instead of using parallel data fetching (e.g., initiating multiple `fetch`/DB calls before awaiting any of them, or using `Promise.all`), and a missing `loading.tsx` for a route whose data-fetching is inherently slow — the documented pattern is to add `loading.tsx` so navigation feels instant while server rendering completes, rather than leaving the user on a blank screen.
+
+## Design rules: code-splitting
+
+1. **Component + loader (+ action) should resolve in parallel for a given lazy route**, not sequentially. Flag `await import(a); await import(b)` sequences that could be `Promise.all([import(a), import(b)])`.
+2. **Check for a `loading.tsx`/equivalent fallback** on any route segment whose data-fetching is non-trivial, so the user gets immediate navigation feedback rather than a frozen UI — absence is a MEDIUM UX/performance finding, not a hard block.
+3. **Don't flag intentional sequential dependencies** — if a `loader` genuinely needs data only available after a component-level decision (rare, and usually a smell in its own right), sequential loading may be correct; verify the dependency is real before flagging.
+
+## Officially grounded URL-state shape
+
+- View-affecting UI state that should be shareable, bookmarkable, or survive a refresh belongs in the URL: a dynamic path segment for identity-like state (`/blog/[slug]`), and search params for filter/pagination/sort/tab state (`?page=2&sort=recent&tab=comments`).
+- React Router and Next.js both provide first-class hooks/utilities for reading and writing search params tied to navigation (`useSearchParams` in both, with framework-specific write patterns) — the presence of one of these being used for a given piece of state is a strong positive signal; the absence of any URL-touching code for filter/tab/pagination UI, combined with a `useState` holding that same data, is the defect pattern to search for.
+
+## Design rules: URL state
+
+1. **Classify each piece of route-level UI state** as either (a) session-only/ephemeral (a dropdown's open/closed state — fine in `useState`) or (b) view-critical/shareable (a filter, page number, active tab, search query, sort order — should be in the URL). Do not flag category (a).
+2. **For category (b) state found only in `useState`/component state with no corresponding search-param or path-segment representation**, flag it — severity depends on whether the route is meant to be shareable or bookmarkable (a report/dashboard/search-results route is usually meant to be; an internal wizard step sometimes isn't — verify intent rather than assuming).
+3. **Verify state survives a hard refresh conceptually**: if the only place a value lives is a `useState` initializer with no URL/`localStorage`/server-state backing, a refresh loses it — that's the concrete, testable definition of the defect, more useful in a finding than "should be in the URL" alone.
+
+## Adversarial checklist
+
+- Does the lazy route's component and loader (and action, if present) resolve via a parallel construct, or did you find a sequential `await` chain?
+- Is there a `loading.tsx`/fallback for routes whose data-fetching is non-trivial?
+- For every filter/pagination/tab/search UI element on a route, did you check whether its state is represented in the URL, or did you only check the ones a bug report already named?
+- If state is in the URL, is it read back out on load (so a shared link actually reproduces the view), not just written on change?
+
+## Safe verification targets
+
+- Grep for `lazy:` route properties and inspect whether their resolution uses `Promise.all` / a single combined import, or separate `await` statements.
+- Grep for `useState` hooks adjacent to filter/tab/pagination UI and cross-reference against `useSearchParams`/`URLSearchParams` usage in the same file.
+- Check for `loading.tsx` (Next.js) or an equivalent pending/fallback UI sibling to slow route segments.