@mrciphersmith/keryx 0.2.163 → 0.3.0

package/src/gdskills/bundled/stacks/react/governance/scout.json

@@ -0,0 +1,40 @@
+[
+  {
+    "query": "Use when building or changing a React component, hook, or form in a .tsx/.jsx file -- covers function components, deriving state instead of syncing it with effects, Suspense and error boundaries, form Actions (useActionState, useOptimistic, useTransition), ref-as-prop, and React Compiler-aware memoization.",
+    "decision": "fork",
+    "topMatch": "react/react-build-fix",
+    "recordedAt": "2026-09-24T12:00:07.391Z",
+    "skillName": "react-implementation",
+    "justification": "top match react/react-build-fix (0.32) is a build/lint/type-error fix skill for already-broken code, not an authoring workflow for new component/hook code; react-code-review (0.24) is read-only review; react-testing (0.18) is test authoring, not component authoring. Below use threshold 0.55; none is a substitute for a React component-authoring skill, so create."
+  },
+  {
+    "query": "Use when a React component's test suite needs writing, extending, or fixing with React Testing Library -- covers query-by-role/label, user-event interaction, async findBy/waitFor, network mocking at the request boundary, and act warnings, on top of the project's Vitest or Jest runner.",
+    "decision": "fork",
+    "topMatch": "ts-js-node/nodejs-testing",
+    "recordedAt": "2026-09-24T12:00:14.111Z",
+    "skillName": "react-testing",
+    "justification": "top match ts-js-node/nodejs-testing (0.46) is the generic TS/Node testing skill with no React component, JSX rendering, or React Testing Library query/interaction guidance; review-testing-practices (0.29) is read-only review, not authoring. Below use threshold 0.55; neither is a substitute for a React-specific RTL authoring skill, so create."
+  },
+  {
+    "query": "Use when reviewing changed React component or hook code (.tsx/.jsx) for Rules of Hooks violations, effect dependency bugs, stale closures, key misuse, in-place state mutation, re-render hot spots, accessibility gaps, and dangerouslySetInnerHTML/URL XSS sinks -- read-only, no MobX store review and no repository convention-doc lookup.",
+    "decision": "create",
+    "topMatch": "react/react-implementation",
+    "recordedAt": "2026-09-24T12:00:23.775Z",
+    "skillName": "react-code-review"
+  },
+  {
+    "query": "Use when a React component fails to type-check, lint, or build -- JSX/TSX prop and children typing errors, event handler and ref types after the React 19 types changes, eslint-plugin-react-hooks failures, and Vite/webpack/Next.js bundler build failures or hydration mismatches. Fixes the root cause, never disables the hooks lint rule or casts to any.",
+    "decision": "fork",
+    "topMatch": "ts-js-node/nodejs-build-fix",
+    "recordedAt": "2026-09-24T12:00:23.917Z",
+    "skillName": "react-build-fix",
+    "justification": "top match ts-js-node/nodejs-build-fix (0.32) is the generic TS/Node build-fix skill with no JSX/TSX prop typing, react-hooks lint, or hydration-mismatch guidance; react-implementation (0.25) is an authoring skill, not a fix skill. Below use threshold 0.55; neither is a substitute for a React-specific build-fix skill, so create."
+  },
+  {
+    "query": "Use when upgrading a codebase across React major versions (e.g. 18 to 19) -- removing legacy APIs (string refs, legacy context, propTypes/defaultProps on function components, ReactDOM.render/hydrate), applying official codemods, updating the @types/react package, fixing the act import, and staging the rollout.",
+    "decision": "create",
+    "topMatch": "react/react-build-fix",
+    "recordedAt": "2026-09-24T12:00:24.073Z",
+    "skillName": "react-upgrade-migration"
+  }
+]

package/src/gdskills/bundled/stacks/react/pack.json

@@ -0,0 +1,42 @@
+{
+  "id": "react",
+  "family": "framework",
+  "extends": "ts-js-node",
+  "modules": ["react-rules", "react-skills"],
+  "detectionMarkers": ["react"],
+  "provenance": {
+    "origin": "authored",
+    "sourceRef": "flow 314, Wave 4 batch 1"
+  },
+  "stability": "experimental",
+  "skills": {
+    "implement": ["react-implementation"],
+    "test": ["react-testing"],
+    "review": ["react-code-review"],
+    "build-fix": ["react-build-fix"],
+    "migrate": ["react-upgrade-migration"]
+  },
+  "agentProfile": {
+    "displayName": "React",
+    "auditFocus": [
+      "Rules of Hooks violations and conditional/loop-nested hook calls",
+      "effect dependency arrays that are wrong, missing, or paper over a needed effect",
+      "state or props mutated in place instead of replaced",
+      "keys on list items that are array index or missing where order can change",
+      "accessibility of interactive elements: semantic tags, labels, focus management",
+      "dangerouslySetInnerHTML or unsanitized user data reaching a DOM sink"
+    ],
+    "buildCommands": [
+      "the project's type-check script (e.g. tsc --noEmit, or its package.json equivalent)",
+      "the project's lint script with the react-hooks plugin enabled",
+      "the project's test script (Vitest/Jest run of React Testing Library suites)",
+      "the project's bundler build (Vite/webpack/Next.js production build)"
+    ],
+    "fixGuardrails": [
+      "never disable or downgrade an eslint-plugin-react-hooks rule to silence a warning",
+      "never cast a component's props, ref, or event handler to any to satisfy the type checker",
+      "never delete or loosen a failing assertion in a React Testing Library test to make it pass",
+      "never wrap a component in unnecessary memo/useMemo/useCallback as a build-fix when the project runs the React Compiler"
+    ]
+  }
+}

package/src/gdskills/bundled/stacks/react/rules/coding-style.mdc

@@ -0,0 +1,58 @@
+---
+extends: common
+paths: ["**/*.tsx", "**/*.jsx"]
+metadata:
+  origin: authored
+---
+
+# React coding style
+
+Narrows `ts-js-node`'s coding style to React component files. Applies only
+to `*.tsx`/`*.jsx` — non-component TypeScript/JavaScript still
+comes from `ts-js-node`'s own coding-style rule, not this file.
+
+## Components
+
+- Write function components; a class component is a maintenance
+  regression unless the project has no alternative (e.g. an error boundary,
+  which still requires a class in current React).
+- One component per file for anything exported and reused; a small private
+  helper component used only inside its parent file can stay local.
+- Name a component file after the component it exports (`UserCard.tsx`
+  exports `UserCard`), `PascalCase` for the component, `camelCase` for
+  hooks (`useUserCard`) and plain functions.
+- Destructure props in the function signature; do not thread a whole
+  `props` object through the body when only a few fields are used.
+- Type props with an explicit `interface`/`type`, not `React.FC` — `FC`'s
+  implicit `children` and weaker generic inference are a known footgun the
+  current React types intentionally do not paper over.
+
+## Hooks and state
+
+- Call hooks only at the top level of a component or another hook, never
+  inside a condition, loop, or nested function — the react-hooks lint rule
+  enforces this; do not add an eslint-disable line to route around it (see
+  `rules/security.mdc` and `react-build-fix`'s guardrails).
+- Order hooks so the same hooks run in the same order on every render;
+  branch inside a hook's own logic (`if (x) return early` after the hook
+  call), not around the hook call itself.
+- Prefer several focused `useState` calls over one large state object when
+  the fields update independently; group into one state (or `useReducer`)
+  only when fields change together.
+- Name a custom hook's return values by what they mean in the caller
+  (`{ data, isLoading, error }`), not by the hook's internal variable
+  names.
+
+## Imports and structure
+
+- Group imports: React/framework, third-party, then local — the same
+  ordering `ts-js-node`'s coding-style rule already asks for; nothing
+  React-specific changes the grouping itself.
+- Import hooks and utilities by name (`import { useState } from "react"`);
+  do not import the whole `React` namespace unless the project's JSX
+  transform requires it (check the project's `tsconfig`/bundler config —
+  the classic transform needs `import React from "react"` in scope, the
+  automatic transform introduced in React 17 does not).
+- Co-locate a component's own styles, tests, and small subcomponents next
+  to it under one directory when the project already uses that layout;
+  match the existing convention rather than introducing a new one.

package/src/gdskills/bundled/stacks/react/rules/patterns.mdc

@@ -0,0 +1,79 @@
+---
+extends: common
+paths: ["**/*.tsx", "**/*.jsx"]
+metadata:
+  origin: authored
+---
+
+# React patterns
+
+Idiomatic component design and anti-patterns for React 19-era code,
+narrowed to `*.tsx`/`*.jsx`.
+
+## Derive, don't sync
+
+- If a value can be computed from existing props/state during render,
+  compute it during render — do not `useState` + `useEffect` to mirror one
+  piece of state into another. A `useEffect` that only calls `setState`
+  from a change in props/state is almost always replaceable by a plain
+  computed value (optionally memoized with `useMemo` when the computation
+  is expensive).
+- Reset local state on a prop change by giving the component a `key` tied
+  to that prop (React unmounts and remounts a fresh component), not by
+  watching the prop in an effect and calling a setter.
+- Effects are for synchronizing with something outside React: the DOM,
+  a subscription, a network request, browser storage, a third-party widget.
+  An effect with no external system on the other end is a sign the logic
+  belongs in an event handler or in render itself.
+
+## Lists and keys
+
+- Every element in a list rendered with `.map` gets a stable `key` drawn
+  from the data (an id), never the array index, unless the list is
+  provably static and never reordered/filtered/inserted into.
+- Do not use `key` as a prop for anything other than list identity inside
+  the component receiving it — reading `props.key` returns `undefined`.
+
+## Forms and events
+
+- Prefer a controlled input (`value` + `onChange`) for anything the
+  component needs to validate, transform, or react to as the user types;
+  use an uncontrolled input (`defaultValue` + a ref) only for simple
+  fire-and-forget fields where per-keystroke reactivity is not needed.
+- For form submission with a pending/error/optimistic result, prefer an
+  Action (a function passed to a `<form action={...}>`,
+  `useActionState`, and `useOptimistic` for the optimistic update) over
+  hand-rolled `isSubmitting`/`error` state plus a submit handler that calls
+  `preventDefault` — the Actions API already tracks pending and error state
+  and integrates with Suspense.
+- Reach for `useTransition` to mark a state update as non-urgent (keeps the
+  UI responsive during an expensive re-render) rather than debouncing or
+  deferring the update by hand.
+
+## Refs, Suspense, and composition
+
+- In React 19, `ref` is an ordinary prop on function components — no
+  `forwardRef` wrapper is needed for a new component that accepts a ref.
+  Keep `forwardRef` only in code that must still support pre-19 React.
+- Read an async resource inside render with the `use` API (for a promise
+  or a context) instead of stuffing the result into state via an effect;
+  pair it with a `Suspense` boundary for the pending state and an error
+  boundary for the rejected state.
+- Prefer composition (children, render props, or a small set of focused
+  components) over one component branching on a `type`/`variant` prop into
+  unrelated render trees.
+- In a framework that supports server and client components, keep data
+  fetching and secrets in server components; a component needs
+  `"use client"` only once it uses state, effects, refs, or browser-only
+  APIs — do not mark a whole subtree client just because one leaf needs it.
+
+## Compiler awareness
+
+- When the project has the React Compiler enabled (check its babel/swc
+  config or `babel-plugin-react-compiler`/`react-compiler` dependency),
+  do not hand-add `memo`, `useMemo`, or `useCallback` purely to prevent
+  re-renders — the compiler already memoizes automatically, and manual
+  memoization on compiled code is dead weight that can also mask a bug the
+  compiler would otherwise have caught. Without the compiler, manual
+  memoization is still a valid, deliberate optimization for a measured
+  re-render cost.

package/src/gdskills/bundled/stacks/react/rules/security.mdc

@@ -0,0 +1,70 @@
+---
+extends: common
+paths: ["**/*.tsx", "**/*.jsx"]
+metadata:
+  origin: authored
+---
+
+# React security
+
+Stack-specific risks for React component files (`*.tsx`/`*.jsx`),
+narrowing `ts-js-node`'s generic security rule. Not a general OWASP list —
+only the sinks React's rendering model makes reachable.
+
+## `dangerouslySetInnerHTML`
+
+- Treat `dangerouslySetInnerHTML` as the default XSS sink: any user-, API-,
+  or CMS-sourced string passed to it renders as live HTML/JS. Avoid it —
+  render the content as text/JSX instead — unless the project genuinely
+  needs to render rich HTML (e.g. a CMS body).
+- When it is unavoidable, sanitize the string through the project's own
+  sanitizer (e.g. DOMPurify) immediately before the prop is built, not
+  earlier in the pipeline where a later edit could drop the sanitize step;
+  never pass a raw string straight through.
+- Never build the `__html` value by concatenating user input into a
+  template string of markup — that is the same sink with extra steps.
+
+## URLs from user data
+
+- Reject or scheme-allowlist a URL that becomes an `href`/`src` when it
+  comes from user input, a query param, or an API response —
+  `javascript:`, `data:`, and `vbscript:` schemes execute on click/load.
+  Validate against an allowlist (`http:`, `https:`, `mailto:`) before
+  binding it to the element.
+- The same applies to a dynamic `src` on `<img>`, `<iframe>`, or `<script>`
+  built from anything not fully controlled by the app.
+
+## Secrets and client bundles
+
+- Anything read via the framework's public-env convention (e.g. a
+  `NEXT_PUBLIC_`/`VITE_`/`REACT_APP_`-prefixed variable, or any value the
+  bundler inlines into client output) ships in the browser bundle in plain
+  text — never put an API secret, private key, or unscoped token behind
+  one of these prefixes. A value that must stay server-only belongs in a
+  server component, a route handler/API route, or a server function/
+  action, never a client component or a plain (non-prefixed-and-still-
+  bundled) constant imported into client code.
+- Grep a diff for the project's public-env prefix before approving a new
+  environment variable used inside a client component.
+- A Server Function/Action is not merely a safe home for a server-only
+  value — calling it from the client turns it into a public, directly
+  reachable HTTP endpoint (its own route, invocable by anything that can
+  reach the app, not only through the form/button that references it in
+  the source). It gets none of the caller-identity or authorization
+  checks a UI-only flow implies; each Server Function/Action must
+  authenticate the caller, authorize the specific operation, and validate
+  every argument itself, exactly as a hand-written API route would,
+  before it touches data or a mutation.
+
+## Third-party scripts and client-side auth
+
+- Loading a third-party script by injecting a `<script>` tag with a
+  dynamic or user-influenced `src` is the same class of risk as an
+  unvalidated `href`/`src` above; pin third-party script URLs to a fixed,
+  reviewed list.
+- Do not gate a protected view purely on client-side state (a store flag,
+  a decoded-but-unverified JWT, a route guard component) — a client
+  component can always be bypassed by disabling JavaScript or calling the
+  underlying API directly. Client-side checks are UX only; the real
+  authorization check must happen server-side (server component, route
+  handler, or backend).

package/src/gdskills/bundled/stacks/react/rules/testing.mdc

@@ -0,0 +1,60 @@
+---
+extends: common
+paths: ["**/*.tsx", "**/*.jsx"]
+metadata:
+  origin: authored
+---
+
+# React testing
+
+Test layout, runner, and assertion conventions for React component files
+(`*.tsx`/`*.jsx`), narrowing `ts-js-node`'s generic testing rule.
+
+## Layout and runner
+
+- Use the project's already-configured runner (Vitest or Jest) and React
+  Testing Library (`@testing-library/react` + `@testing-library/user-event`)
+  — do not introduce Enzyme or a shallow-render helper into a project that
+  does not already use one.
+- Co-locate a component's test next to it (`UserCard.test.tsx`) when the
+  project already follows that layout, or under a mirrored `__tests__`
+  tree when that is the existing convention; match, do not introduce.
+
+## Queries and interaction
+
+- Query by role/label/text the way a user or assistive technology would
+  (`getByRole`, `getByLabelText`, `getByText`) — reach for `data-testid`
+  only when no accessible query exists, and treat that as a sign the
+  markup itself may be missing an accessible name.
+- Never assert on a component's internal state, instance fields, or
+  implementation details (no reaching into a ref's internals, no snapshot
+  of a component's private props) — assert on rendered output and
+  behavior only.
+- Drive interaction through `@testing-library/user-event`
+  (`userEvent.click`/`.type`/`.tab`), not `fireEvent`, unless the project
+  is pinned to an older `user-event` major that cannot express the
+  interaction — `user-event` fires the fuller sequence of browser events a
+  real interaction would.
+
+## Async and network
+
+- Wait for async UI with `findBy*` queries or `waitFor`, never a manual
+  `setTimeout`/`sleep` — an arbitrary delay is both slow and flaky under
+  load.
+- Mock network calls at the request boundary (an MSW handler, or the
+  project's existing equivalent) rather than mocking the component's own
+  data-fetching function — a boundary mock still exercises the real
+  fetch/parse/error-handling code path.
+- Wrap a state update triggered outside React Testing Library's own query
+  helpers (e.g. a manually invoked callback) in `act` only when RTL's
+  built-in wrapping does not already cover it; an `act` warning is a
+  signal to await the right query, not to silence the console.
+
+## Coverage expectations
+
+- Cover the rendered states a component can be in: initial/loading,
+  success, error, and empty, plus any conditional branch a prop or piece
+  of state gates.
+- For a custom hook with logic worth testing on its own, use
+  `renderHook` from `@testing-library/react` rather than mounting a
+  throwaway component to exercise it.

package/src/gdskills/bundled/stacks/react/skills/react-build-fix/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: react-build-fix
+description: "Use when a React component fails to type-check, lint, or build -- JSX/TSX prop and children typing errors, event handler and ref types after the React 19 types changes, eslint-plugin-react-hooks failures, and Vite/webpack/Next.js bundler build failures or hydration mismatches. Fixes the root cause, never disables the hooks lint rule or casts to any."
+triggers:
+  - "fix this tsx type error"
+  - "react-hooks lint is failing"
+  - "vite build is failing on this component"
+  - "hydration mismatch error"
+  - "ref type error after upgrading react types"
+  - "children prop type error"
+metadata:
+  origin: authored
+  category: build-fix
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# React build fix
+
+Fix a failing type-check, lint, or bundler build caused by React component
+code. Scoped to failures that originate in `.tsx`/`.jsx` component code or
+its JSX/hooks typing — a failure with no React-specific cause (a plain
+module import error, a Node config issue) is `ts-js-node`'s build-fix
+skill, not this one.
+
+## Workflow
+
+### Step 1: Reproduce and classify
+
+Run, in order, until one fails (use `agentProfile.buildCommands` from
+`pack.json` as the starting point, adjusted to the project's actual
+scripts):
+
+1. Type-check (`tsc --noEmit` or the project's script).
+2. Lint, with `eslint-plugin-react-hooks` enabled.
+3. Test run.
+4. Bundler build (Vite/webpack/Next.js).
+
+Read the first failure's full message — do not guess from the file name.
+Classify it as: JSX/TSX typing (props, children, events, refs), hooks-lint
+(`react-hooks/rules-of-hooks`, `react-hooks/exhaustive-deps`), or bundler/
+hydration.
+
+### Step 2: Fix JSX/TSX typing errors
+
+- Props typing error: fix the `interface`/`type` to match how the
+  component is actually used, or fix the call site — do not widen the
+  prop type to `any`/`unknown` to make the error disappear.
+- Children typing: type `children` explicitly (`React.ReactNode` for
+  arbitrary children, a narrower type when only specific children are
+  valid) rather than accepting `any`.
+- Event handler typing: use the specific React event type for the element
+  and event (`React.ChangeEvent<HTMLInputElement>`,
+  `React.MouseEvent<HTMLButtonElement>`), not a hand-rolled loose type.
+- Ref typing after the React 19 types change (`ref` as an ordinary prop
+  on function components): type it as
+  `React.Ref<ElementType>`/`React.RefObject<ElementType>` matching what
+  the component actually forwards; if the project is still on
+  `forwardRef`, match `forwardRef`'s own generic signature instead of
+  mixing the two patterns in one component.
+
+### Step 3: Fix hooks-lint errors
+
+- `rules-of-hooks` violation: restructure so the hook call is
+  unconditional and top-level — move the condition inside the hook's own
+  logic, or split into two components/hooks. Never add an
+  `eslint-disable-next-line react-hooks/rules-of-hooks` comment.
+- `exhaustive-deps` violation: add the missing reactive dependency, or, if
+  the value is intentionally stable (a ref, a dispatch function, a value
+  the author has confirmed never needs to trigger the effect), use the
+  lint rule's own escape hatch documented for that case rather than a
+  blanket disable comment — and only after confirming the value truly
+  cannot change in a way the effect needs to react to.
+
+### Step 4: Fix bundler and hydration failures
+
+- Bundler build failure: read the actual bundler error (missing export,
+  bad dynamic import, unsupported syntax for the configured target) and
+  fix the source or import, not the bundler config, unless the config
+  itself is provably wrong for the project's stated target.
+- Hydration mismatch: find what differs between server and client render
+  — a `Date`/`Math.random`/`typeof window` branch evaluated during render,
+  locale/timezone-dependent formatting, or state initialized differently
+  on each side. Fix by making the server and first client render produce
+  identical output (move the divergent value into an effect that runs
+  post-hydration, or pass it down as a prop already resolved server-side)
+  — do not silence the warning by wrapping the whole tree in a
+  client-only guard unless the divergent content is genuinely
+  client-only.
+
+### Step 5: Verify and report
+
+```bash
+keryx test run --changed --strict
+```
+
+Re-run the exact command that failed in Step 1 and confirm it now exits 0,
+then re-run the full chain (type-check, lint, test, build) once to confirm
+the fix did not break an earlier step.
+
+```
+Fixed: src/components/UserCard.tsx:18 — onSave typed as
+  React.MouseEvent<HTMLButtonElement> to match the actual click handler
+  signature; tsc --noEmit now passes.
+```
+
+## Rules
+
+- ALWAYS fix the root cause with the smallest change that resolves it.
+- NEVER disable or downgrade `eslint-plugin-react-hooks` rules to make a
+  lint failure disappear.
+- NEVER cast a prop, ref, or event to `any`/`as any` to silence a type
+  error.
+- NEVER delete or loosen a failing test assertion to make a build/test
+  step pass.
+- Stop after 3 fix iterations on the same failure and report what remains,
+  rather than escalating to a disable/cast/deletion.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll add eslint-disable-next-line to get lint green" | Silences a rule designed to catch a real class of runtime bug (stale closures, hook-order crashes); fix the dependency or hook placement instead |
+| "This type error is annoying, I'll cast to any" | Removes the type check entirely at that point, including for the next person's edit; fix the actual type mismatch |
+| "The hydration warning is harmless, I'll wrap everything in a client-only check" | Over-broad client-only guards flash empty/loading content for content that could have rendered on the server; find the actual server/client divergence first |
+| "Test's failing after my fix, I'll just skip it" | Skipping hides a real regression the build-fix may have introduced; investigate before moving on |
+
+## Verification
+
+Do not report the work done until all of the following hold:
+
+- The exact command that failed in Step 1 now exits 0.
+- The full chain (type-check, lint, test, build) still passes after the
+  fix — a fix to one step did not regress an earlier one.
+- No `eslint-disable` comment was added for a hooks rule, and no `as any`/
+  `: any` was added to route around a type error.
+- `git status` shows only the files whose failure was being fixed (plus
+  their types, if the fix was a type definition change).

package/src/gdskills/bundled/stacks/react/skills/react-build-fix/evals.json

@@ -0,0 +1,72 @@
+{
+  "triggers": {
+    "positive": [
+      "This component's ref prop is throwing a TSX type error after the React 19 upgrade, fix it",
+      "eslint-plugin-react-hooks is failing on exhaustive-deps in this file",
+      "The Vite build fails with a JSX syntax error in this component",
+      "I'm getting a hydration mismatch warning on this page, fix it",
+      "Fix this children prop type error in the component",
+      "The tsc build fails because this event handler's type doesn't match onChange"
+    ],
+    "negative": [
+      "Write a new test for this component's error state",
+      "Review this component for Rules of Hooks violations",
+      "Migrate this codebase from React 18 to React 19",
+      "Build a new dashboard component with charts",
+      "Fix a Node.js module resolution error unrelated to any component",
+      "This component re-renders too often, help me optimize it"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "no-disable-hooks-lint",
+      "prompt": "react-hooks/exhaustive-deps is failing on my useEffect because it's missing a dependency. What should I do to fix the build?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer fixes the exhaustive-deps failure by adding the missing reactive dependency to the effect's dependency array, or, if the value is genuinely stable (a ref, a dispatch function, a value confirmed never to change in a way the effect needs), uses the lint rule's own documented escape hatch after explaining why the value is stable. It treats the failure as a real staleness bug to fix, not noise to silence.",
+          "pass_criteria": [
+            "Names the specific missing dependency the effect reads and shows the corrected code — either the completed dependency array including it or a useCallback/useRef restructuring so the value no longer needs to be listed. When the prompt itself shows no code (as here), a concrete illustrative example of such a corrected effect/dependency array satisfies this requirement. A plain 'add the dependency' with no named value and no code shown does not satisfy this.",
+            "Explains the staleness consequence of the missing dependency (the effect would keep using an old/stale value from an earlier render instead of reacting to the current one), not just that the fix 'resolves the issue' or 'stops the build complaining'."
+          ],
+          "fail_criteria": [
+            "Recommends disabling or suppressing the exhaustive-deps rule (for example an eslint-disable-next-line comment) as the fix, instead of adding the missing dependency or justifying a stability-based exception; this includes mentioning eslint-disable only as a caveat or aside without a concrete named-dependency fix alongside it."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Add the dependency the effect actually reads to its dependency array — that's what exhaustive-deps is flagging, and it's usually a real staleness bug, not a false positive. For example, if the effect fetches data using a prop:\n\nuseEffect(() => {\n  fetchUser(userId);\n}, [userId]);\n\nWithout userId in the array, the effect only runs once and keeps using whatever userId was passed on the first render — if the prop changes later, the effect won't re-fire and fetchUser keeps being called with a stale id instead of the current one, which is exactly the staleness bug the rule exists to catch. If adding the value would cause the effect to re-run on every render because it's a function or object recreated each render, wrap that value in useCallback/useMemo in its own definition rather than dropping it from the array:\n\nconst fetchUser = useCallback((id: string) => { /* ... */ }, []);\nuseEffect(() => {\n  fetchUser(userId);\n}, [userId, fetchUser]);\n\nOnly omit a value from the array when you've confirmed it's genuinely stable across renders — a ref, a setState/dispatch function, or a value you've verified never changes in a way this effect cares about — and in that case use the rule's documented per-line justification rather than a blanket eslint-disable-next-line comment. Don't just silence the rule; an eslint-disable comment here would hide the bug instead of fixing it.",
+        "known_wrong": "Easiest fix: add `// eslint-disable-next-line react-hooks/exhaustive-deps` right above the useEffect line. That silences the warning so your build/lint step goes green immediately, and you don't need to touch the dependency array or worry about extra re-renders. Just drop that comment in and move on — the effect will keep working the same way it does now, the lint rule just won't complain anymore.",
+        "vague": "Add what's missing to the dependency array, or otherwise adjust the effect so the lint rule stops flagging it. That should clear the build.",
+        "subtle_wrong": "Add the missing value to the dependency array — that's the general fix here. Once you do that, if you notice the effect re-running more than you'd like because of it, you can always wrap the eslint-disable-next-line comment around just that specific line as a targeted exception rather than disabling the whole rule file-wide; that keeps the rest of the codebase's exhaustive-deps checking intact while unblocking this one build failure quickly."
+      },
+      "anti_patterns": ["eslint-disable"]
+    },
+    {
+      "id": "no-any-cast",
+      "prompt": "I have a TSX prop type error on an event handler and the build is failing. Should I just cast it to any to unblock the build?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer says no, casting to any is not the fix, and instead resolves the actual type mismatch by typing the event handler parameter with the specific React event type that matches the element and event in use (for example React.ChangeEvent<HTMLInputElement> or React.MouseEvent<HTMLButtonElement>), so the type check reflects reality instead of being bypassed.",
+          "pass_criteria": [
+            "States that casting to any is not the right fix for this prop type error.",
+            "Names the specific React event type that matches the element/event in use (for example React.ChangeEvent<HTMLInputElement> or React.MouseEvent<HTMLButtonElement>), not just 'the correct event type' in the abstract."
+          ],
+          "fail_criteria": [
+            "Recommends casting the prop/event to any (or `as any`) as the way to unblock the build, including as a temporary/fallback suggestion alongside the real fix."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "No — casting to any would remove type checking at that call site entirely, including for whatever the next person changes there, and it doesn't actually fix anything, it just hides the mismatch. Look at what element and event you're actually handling: for an <input> onChange it's React.ChangeEvent<HTMLInputElement>, for a button click it's React.MouseEvent<HTMLButtonElement>, for a form submit it's React.FormEvent<HTMLFormElement>. Update the handler's parameter type to match the specific element/event combination instead of whatever loose or generic type it currently has. If you're not sure which one applies, check how the handler is wired up in JSX (onChange, onClick, onSubmit) — that tells you the event type. Once the parameter type matches what's actually being passed, the type error goes away because the code is now honestly described, not suppressed. Re-run the build after the change to confirm it's green.",
+        "known_wrong": "Yeah, just cast it `as any` for now — `(e as any).target.value` or type the handler param `(e: any) => { ... }` — and the type error will go away so your build unblocks. You can always circle back and add the proper React.ChangeEvent type later if it becomes an issue; for now the `as any` cast gets you moving without having to dig into exactly which event type the handler needs.",
+        "vague": "No, don't cast to any — fix the event handler's type instead so it matches what's actually being passed in.",
+        "subtle_wrong": "Casting to any isn't great long-term, so instead give the parameter a narrower type than any, like `(e: React.SyntheticEvent) => { const target = e.target as HTMLInputElement; ... }`. That keeps some type safety at the boundary while letting you unblock the build now; you can tighten it to the exact ChangeEvent/MouseEvent generic later once you've confirmed which element this handler actually attaches to."
+      },
+      "anti_patterns": ["as any"]
+    }
+  ]
+}