@mrciphersmith/keryx 0.2.164 → 0.3.1

package/src/gdskills/bundled/stacks/react/skills/react-code-review/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: react-code-review
+description: "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."
+triggers:
+  - "review this react component diff for hook and jsx bugs"
+  - "check the react hooks in this pull request for rules of hooks violations"
+  - "does this react useEffect have a dependency array bug"
+  - "review this component for accessibility"
+  - "any stale closure in this hook"
+  - "check for xss in this jsx"
+metadata:
+  origin: authored
+  category: review
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# React code review
+
+Read-only review of changed `.tsx`/`.jsx` component/hook code against
+React's own correctness and accessibility model. This skill never edits
+code — it reports findings for a human or a follow-up fix skill
+(`react-build-fix`) to act on.
+
+**Scope boundary (read this before triggering):** this skill checks
+React's rendering/hooks model itself — Rules of Hooks, effect
+dependencies, closures, keys, mutation, re-renders, accessibility, and DOM
+XSS sinks. It does NOT review MobX (or any other) state-management-library
+usage (observers, actions, stores, reactions — that is a store-review
+skill's job) and it does NOT check a repository's own local convention
+docs (CLAUDE.md-style rules, i18n placement, styling tokens — that is a
+convention-review skill's job). On a diff that touches both plain React
+concerns and a state-management store, run this skill for the component
+side and the appropriate store-review skill for the store side; see
+`governance/scout.json` for why these stay separate skills instead of one
+merged reviewer.
+
+## Workflow
+
+### Step 1: Scope the diff
+
+1. Identify changed `.tsx`/`.jsx` files and, within them, changed hooks,
+   effects, event handlers, and JSX return blocks — line-level, not the
+   whole file, unless the whole file is new.
+2. Note the React major and whether the React Compiler is enabled
+   (changes whether manual memoization is a finding or a non-issue).
+3. Skim 1 file of surrounding context per changed component to know its
+   existing prop/state shape — a review without context misreads intent.
+
+### Step 2: Check hooks correctness
+
+- Rules of Hooks: any hook called conditionally, in a loop, after an early
+  return, or inside a plain (non-hook, non-component) function — flag as a
+  correctness bug, not a style note. A guard clause sitting above a hook
+  call is the most common shape to catch: when a component bails out early
+  (a null-prop guard, a loading check written as `return` instead of a
+  conditional in the JSX) before it reaches its `useState`/`useEffect`/
+  `useMemo`/`useCallback` calls, those hooks run on some renders and not
+  others, which breaks React's per-render hook ordering. The fix is to
+  move every hook call above the first `return`, then branch inside the
+  returned JSX or inside the hook's own callback instead.
+- Effect dependency arrays: every reactive value read inside the effect
+  body appears in the dependency array, or the omission is deliberate and
+  safe (a ref, a setState function) — a missing dependency that reads a
+  prop/state value is a real staleness bug, not a lint nag to suppress.
+- Stale closures: a callback (event handler, effect body, timer callback)
+  that captures a prop/state value from an earlier render and is not
+  re-created when that value changes — look especially at
+  `useCallback`/`useMemo` dependency arrays and any handler stored in a
+  ref for later use.
+- An effect whose only job is to call `setState` from a prop/state change
+  it could instead derive during render — flag per `rules/patterns.mdc`
+  ("Derive, don't sync"), since it usually signals a design bug, not a
+  missing dependency.
+
+### Step 3: Check rendering correctness
+
+- List `key`s: array index used as `key` on a list that can reorder,
+  filter, or have items inserted/removed — flag as a bug (broken local
+  state/focus/animation across reorders), not a style nit.
+- Mutation: props, state, or a value derived from either mutated in place
+  (`.push`, `.sort`, direct property assignment) instead of replaced —
+  React relies on referential identity to detect changes.
+- Re-render hot spots: a new object/array/function literal created inline
+  in a hot render path and passed to a memoized child, defeating the
+  memoization; an expensive computation run on every render with no
+  memoization and no compiler to catch it.
+
+### Step 4: Check accessibility and security
+
+- Semantic elements over generic `div`/`span` with a click handler
+  (`<button>` for actions, proper heading levels, form labels associated
+  via `htmlFor`/`id` or wrapping).
+- Focus management: a modal/dialog that traps and restores focus, a route
+  change that resets focus/announces to assistive tech where the project
+  already has a pattern for it.
+- `dangerouslySetInnerHTML` with unsanitized input, a `javascript:`-scheme
+  URL reaching `href`/`src` from user data, or a secret read through a
+  public-env-prefixed variable inside client code — all per
+  `rules/security.mdc`.
+
+### Step 5: Report
+
+Findings only, grouped by severity, each with file:line, the concrete bug
+(not a style preference), and the fix direction — never a code edit:
+
+```
+CRITICAL: src/components/UserList.tsx:42 — array index used as key on a
+  filterable list; local input state will attach to the wrong row after a
+  filter change. Use item.id as the key.
+HIGH: src/hooks/useUserSearch.ts:18 — effect reads `query` but the
+  dependency array is `[]`; search will silently use the first-render
+  query forever.
+```
+
+## Rules
+
+- NEVER edit code — findings only.
+- NEVER report a plain style preference (naming, formatting) as a
+  correctness finding; route that to a style/convention reviewer instead.
+- NEVER flag MobX observer/action/store patterns — out of scope for this
+  skill (see Scope boundary above).
+- ALWAYS give a concrete fix direction, not just "this looks wrong."
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "This effect's missing dependency is probably intentional, I'll skip it" | A missing dependency on a value the effect body actually reads is a staleness bug more often than an intentional omission; call it out and let the author confirm intent explicitly |
+| "The store looks off too, I'll flag the MobX action pattern while I'm here" | Out of scope for this skill by design — flag the React-side finding and note the store needs its own store-review pass, do not blur the two |
+| "Index-as-key is common, I won't flag it unless the list is huge" | The bug (broken identity across reorders) does not depend on list size; flag it whenever the list can reorder, filter, or splice regardless of length |
+| "I'll just fix the dependency array myself since it's a one-line change" | This skill is read-only; even a one-line fix belongs to a fix skill or the author, reported as a finding, not applied |
+
+## Verification
+
+Before reporting, confirm:
+
+- Every finding cites a specific file:line and a concrete bug, not a
+  vague concern.
+- No finding is actually a MobX/store-pattern issue or a repository
+  convention-doc issue (those belong to other review skills).
+- Rules of Hooks and effect-dependency findings were checked against the
+  actual reactive values read in each effect/callback body, not assumed
+  from the dependency array alone.
+- Accessibility and security findings reference `rules/security.mdc` or a
+  concrete WCAG-relevant gap (missing label, wrong semantic element),
+  not a generic "consider accessibility" note.

package/src/gdskills/bundled/stacks/react/skills/react-code-review/evals.json

@@ -0,0 +1,74 @@
+{
+  "triggers": {
+    "positive": [
+      "Review this pull request's React components for Rules of Hooks violations",
+      "Check this useEffect for a dependency array bug before we merge",
+      "Look at this diff for stale closures in the event handlers",
+      "Review this list render for key misuse",
+      "Check this component diff for a dangerouslySetInnerHTML XSS risk",
+      "Review this modal component for accessibility gaps"
+    ],
+    "negative": [
+      "Review the MobX store actions and reactions in this diff",
+      "Review this diff against our repository's CLAUDE.md frontend conventions",
+      "Write a React Testing Library test for this component",
+      "Fix the failing react-hooks lint error in this file",
+      "Review this NestJS controller's DTO validation",
+      "Build a new component that renders a paginated user list"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "flag-rules-of-hooks",
+      "prompt": "Review this snippet: `function UserPanel({ id }) { if (!id) return null; const [user, setUser] = useState(null); useEffect(() => { fetchUser(id).then(setUser); }, [id]); return <div>{user?.name}</div>; }` What's wrong?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct review identifies that useState and useEffect are called after an early return (`if (!id) return null`), which means the hooks run on some renders and not others — a Rules of Hooks violation, not a style nit. It recommends restructuring so every hook call sits above the first return, branching inside the JSX or inside the hook's own logic instead.",
+          "pass_criteria": [
+            "Names both hooks (useState and useEffect) and states specifically that they sit after `if (!id) return null`, so on renders where id is falsy React never reaches them — a generic 'hooks are called conditionally' without pointing at this early return does not satisfy this.",
+            "Flags this as a real correctness bug (hook call order breaking React's per-render matching) rather than a style preference.",
+            "Shows or describes the concrete restructuring: hoist useState/useEffect above the `if (!id) return null` guard (or push the id-check inside the effect body), not just 'reorder things'."
+          ],
+          "fail_criteria": [
+            "Says the code is fine or does not flag the early-return-before-hooks structure as a problem.",
+            "Treats the issue as a minor style nit rather than a correctness bug.",
+            "Proposes keeping the hooks reachable only conditionally (e.g. wrapping the hook call itself in a condition) instead of moving them above the early return."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "This violates the Rules of Hooks. `useState` and `useEffect` are called after `if (!id) return null;`, so on renders where `id` is falsy the component returns before ever reaching those hook calls, while on renders where `id` is truthy it does reach them. React relies on hooks being called in the exact same order on every render of a given component instance to match state slots correctly — a conditional early return before a hook call breaks that guarantee and can cause React to throw or silently corrupt state/effect ordering, especially once `id` toggles between falsy and truthy across renders. The fix is to move `useState` and `useEffect` above the guard clause so they always run, and move the conditional logic into the returned JSX instead: keep the two hook calls first, then do `if (!id) return null;` right before the `return <div>...`, or push the id-check into the effect body itself so the effect early-returns internally rather than the component bailing out before the hook call.",
+        "known_wrong": "This looks fine to me — the early return is just a standard loading/guard pattern, and since `id` is a prop passed in from the start, in practice the component either always has an id or never does for a given usage, so the hooks effectively always run the same way in that context. I wouldn't block this; maybe add a short comment above the guard explaining why it's there, but the hook order isn't really a concern here since React only cares about hook order within a single component's re-renders, not across different components.",
+        "vague": "This has a Rules of Hooks issue — the hooks are placed after a conditional return, which isn't allowed. You'll want to restructure it.",
+        "subtle_wrong": "Good catch potential here — technically useState/useEffect come after the early return, which is a Rules of Hooks smell. I'd flag it in a comment for awareness, but since `id` only toggles rarely in this component's actual usage (it's set once from a route param) it's unlikely to bite in practice, so I wouldn't block the PR over it — worth a follow-up cleanup ticket rather than a blocking change now."
+      }
+    },
+    {
+      "id": "no-mobx-scope",
+      "prompt": "Review this component diff: it uses a MobX observer wrapping a component with a useEffect that has a missing dependency, and the store action mutates an array in place. What do you flag, and what do you leave to another reviewer?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct review flags the missing effect dependency as a React-side correctness bug (this skill's own scope), and explicitly declines to review the MobX store's in-place array mutation, noting that MobX/store-pattern review belongs to a separate store-review skill or reviewer rather than blurring the two into one finding.",
+          "pass_criteria": [
+            "Flags the missing effect dependency as a concrete staleness bug (explains that the effect will keep using an old value from an earlier render instead of the current one), not just 'the effect is missing a dependency'.",
+            "Explicitly names MobX/store review as a separate reviewer or skill that the in-place array mutation should go to, rather than a vague 'someone else can look at that' or silently reviewing/fixing it itself."
+          ],
+          "fail_criteria": [
+            "Reviews or gives fix guidance on the MobX store action's mutation pattern as if it were this skill's own finding, instead of deferring it.",
+            "Fails to flag the missing effect dependency at all."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "I'll flag the useEffect: it's missing a dependency, which means it will use a stale value from an earlier render instead of reacting to the current one — that's a real staleness bug on the React side and squarely in scope here. Add the missing reactive value read inside the effect body to its dependency array (or confirm it's a stable ref/dispatch function if it's deliberately omitted). On the store action mutating an array in place — I'm noting it exists, but I'm not reviewing or fixing that pattern here. MobX observer/action/store correctness (whether in-place mutation is fine under MobX's own reactivity model, or should be an immutable replace) is out of scope for this skill; that needs a pass from the store-review skill/reviewer, since MobX has its own conventions for what's safe to mutate versus replace. Please route the store action to that review separately.",
+        "known_wrong": "Two things here. First, the missing effect dependency — add it in. Second, the store action mutating the array in place is also worth fixing: MobX generally wants actions to replace arrays immutably rather than push/splice in place so downstream computeds and reactions pick up the change reliably, so I'd rewrite that action to use `array = [...array, newItem]` (or the MobX-friendly equivalent) instead of `array.push(newItem)`. Both changes should go in before merging.",
+        "vague": "I'd flag the effect dependency issue since that's in scope here, and leave the store mutation question to whoever reviews the MobX side.",
+        "subtle_wrong": "The effect dependency looks off, so add whatever's missing there. On the array mutation — since it's a small, contained change and I already have context on it from this diff, I'll just note that MobX generally prefers immutable updates and suggest swapping the push for a spread; no need to route it to a separate MobX review for something this minor."
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,140 @@
+---
+name: react-implementation
+description: "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."
+triggers:
+  - "build a react component"
+  - "add a hook to this component"
+  - "convert this form to use an action"
+  - "this react component re-renders too often, memoize it or check the compiler"
+  - "add suspense boundary"
+  - "wire up useOptimistic"
+  - "when should this be a react server component vs a client component"
+metadata:
+  origin: authored
+  category: implement
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# React implementation
+
+Build or change a React component, hook, or form in `.tsx`/`.jsx` files,
+following current (React 19-era) practice. Scoped to React's own component
+model — generic TypeScript/Node authoring (module structure, error
+handling, non-component logic) is `ts-js-node`'s implementation skill, not
+this one; see `governance/scout.json` for why this needed its own skill
+rather than a fork.
+
+## Workflow
+
+### Step 1: Discover the project's React conventions
+
+1. Check the React major in use (`package.json`'s `react`/`react-dom`
+   version) and whether the React Compiler is enabled (a
+   `babel-plugin-react-compiler`/`react-compiler` dependency or babel/swc
+   config entry) — this changes whether manual memoization is wanted.
+2. Identify the framework, if any (Next.js/Remix/plain Vite/CRA-successor)
+   — it determines whether server/client components and Actions exist as a
+   concept in this project at all.
+3. Read 1-2 neighboring components for: function-vs-class (should always
+   be function for new code), props-typing style, state-management library
+   in use (plain hooks, MobX, Redux, Zustand, Jotai), and file/test
+   co-location.
+4. If a state-management library is in use for this component's slice of
+   state, defer to that library's own conventions for where state lives —
+   this skill covers React's own hook/effect/render model, not a specific
+   store library's API.
+
+### Step 2: Design the component
+
+- Decide what is props, what is local state, and what is derived — a
+  value computable from existing props/state during render is not state
+  (`rules/patterns.mdc`, "Derive, don't sync").
+- Decide what needs an effect: only synchronization with something outside
+  React (subscription, DOM measurement, non-React widget, browser storage).
+  A data fetch has a better home when the framework offers one
+  (a loader, a server component, a query library) — reach for a bare
+  `useEffect` fetch only when the project has none of those.
+- For a form, decide upfront whether it needs a pending/optimistic/error
+  UI. If so, plan for `<form action={...}>` + `useActionState` (+
+  `useOptimistic` for the optimistic path) instead of manual submit-handler
+  state.
+- For a component the caller may need to focus, measure, or imperatively
+  control, accept `ref` as an ordinary prop (React 19) rather than wrapping
+  in `forwardRef`, unless the project is still on React 18 or earlier.
+
+### Step 3: Implement
+
+1. Function component, typed props via `interface`/`type` (not `React.FC`).
+2. Keep hooks unconditional and top-level (`rules/coding-style.mdc`).
+3. Give every list item a stable, data-derived `key`.
+4. Wrap an async read (`use(promise)` or a data-fetching boundary) with a
+   `Suspense` fallback for the pending state and an error boundary for the
+   rejected state.
+5. In a server/client-component framework, keep data fetching and secrets
+   in server components; add `"use client"` only to the leaf that actually
+   needs state, effects, refs, or browser APIs.
+6. Apply `rules/security.mdc` to anything touching `dangerouslySetInnerHTML`,
+   a dynamic `href`/`src`, or a public-env-prefixed variable.
+7. Only add `memo`/`useMemo`/`useCallback` for a measured re-render cost
+   when the React Compiler is NOT enabled for this project (Step 1); when
+   it is enabled, let the compiler handle memoization.
+
+### Step 4: Verify
+
+```bash
+keryx test run --changed --strict
+```
+
+Run the project's own type-check and lint (with the `react-hooks` plugin)
+if `keryx test run` does not already cover them. Fix failures by changing
+the component, not by loosening a type or disabling a hooks-lint rule.
+
+### Step 5: Report
+
+```
+Changed: src/components/UserCard.tsx
+  - converted local sync-effect to a derived value
+  - added useActionState for the save form
+  - tests: keryx test run --changed --strict passing
+```
+
+## Rules
+
+- ALWAYS derive a value from existing props/state during render instead of
+  syncing it into state via an effect, when the value is computable
+  without an external round-trip.
+- ALWAYS give hooks a stable call order — no hook inside a condition, loop,
+  or callback.
+- NEVER use the array index as a list `key` when the list can reorder,
+  filter, or insert.
+- NEVER pass unsanitized user-sourced HTML to `dangerouslySetInnerHTML`
+  (`rules/security.mdc`).
+- Match the project's existing state-management library instead of
+  introducing a second one for one component.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll add a useEffect that calls setState whenever this prop changes" | Almost always a derivable value or a `key`-based remount, not an effect — an effect that only mirrors state adds a render, a flash of stale UI, and a dependency-array bug surface |
+| "This list is short, index as key is fine" | A short list can still reorder or have items removed; index keys corrupt component identity and local state (input focus, animation) across a reorder |
+| "The compiler is on but I'll wrap it in useMemo anyway, can't hurt" | Manual memoization on compiled code is dead weight and can hide a case the compiler would otherwise have caught cleanly — trust the compiler when it is enabled |
+| "I'll sanitize this HTML string somewhere upstream, not right here" | A sanitize step far from the sink is one refactor away from being silently dropped; sanitize immediately before the `dangerouslySetInnerHTML` prop is built |
+| "I'll just cast this ref/event to any, the types are being annoying" | The types changed on purpose in recent React majors (ref-as-prop, stricter event types); route through `react-build-fix` to fix the real typing instead of casting away the check |
+
+## Verification
+
+Do not report the work done until all of the following hold:
+
+- No hook is called conditionally, in a loop, or after an early return —
+  order is identical on every render.
+- Every list `.map` render has a stable, data-derived `key`.
+- Any effect added is synchronizing with something outside React, not
+  mirroring existing props/state into a second state value.
+- `dangerouslySetInnerHTML`, if used, sanitizes input immediately before
+  the prop is built (`rules/security.mdc`).
+- `keryx test run --changed --strict` (or the project's own type-check +
+  lint + test commands) exits 0.
+- `git status` shows only the intended component/hook/test files changed.

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

@@ -0,0 +1,74 @@
+{
+  "triggers": {
+    "positive": [
+      "Implement a new React function component with useState and useEffect for the user profile page",
+      "This component has a useEffect that just copies a prop into state, can you clean it up",
+      "Add a save button to this form using useActionState with an optimistic update",
+      "Wrap this list render in a Suspense boundary with an error boundary fallback",
+      "Convert this class component to a function component with hooks",
+      "This ref prop is throwing a type error, wire it up the React 19 way without forwardRef",
+      "Add useTransition to this React component so typing in the search input does not block rendering"
+    ],
+    "negative": [
+      "Write pytest fixtures for this Django view",
+      "Review this component diff for Rules of Hooks violations and stale closures",
+      "The vite build is failing with a JSX syntax error, fix the build",
+      "Upgrade our app from React 18 to React 19 and run the codemods",
+      "Write a React Testing Library test that clicks a button and checks the modal opens",
+      "Add error handling and structured logging to this Node Express route handler"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "derive-not-sync",
+      "prompt": "This React component has a useEffect that calls setState every time the `user` prop changes, just to copy user.name into a local `displayName` state variable used only for rendering. How should I fix it?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer recognizes that `displayName` is fully computable from the `user` prop and should be derived during render instead of synchronized into a second state variable via an effect. It removes the sync-effect/setState pattern and replaces it with a directly derived value (a plain expression, or useMemo if the derivation is expensive), rather than keeping the effect and just tweaking it.",
+          "pass_criteria": [
+            "Shows or names the concrete derived replacement (a plain expression such as `user.name`, or `useMemo` for an expensive case), not just 'derive it during render' in the abstract.",
+            "Explicitly removes both the useState slot for displayName and the useEffect that set it, not just the effect alone."
+          ],
+          "fail_criteria": [
+            "Keeps the useEffect that calls setState to copy the prop into state as the recommended fix, instead of eliminating the sync effect."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Drop the state variable and the effect entirely — `displayName` is just `user.name`, and any value that's fully computable from existing props/state during render shouldn't live in its own state slot, because syncing it there via an effect adds an extra render pass (the effect runs after the initial render, so there's a flash where displayName is stale/undefined) and opens up a dependency-array bug surface for no benefit. Replace it with a plain derived expression: `const displayName = user.name;` computed inline where you use it, or `const displayName = useMemo(() => computeDisplayName(user), [user])` only if the derivation is genuinely expensive (a simple property read like this isn't). Delete the `useState` for displayName and the `useEffect` that set it — there's nothing left to synchronize once the value is derived directly on every render from the prop that's already available.",
+        "known_wrong": "Keep the effect, just fix the timing — add `user.name` specifically to the dependency array instead of the whole `user` object so it only re-syncs when the name actually changes: `useEffect(() => { setDisplayName(user.name); }, [user.name]);`. That avoids extra re-renders when other parts of `user` change but the name doesn't, which should clean up the behavior you're seeing without having to restructure how displayName is stored.",
+        "vague": "Instead of syncing it with an effect, just derive displayName from the user prop directly during render.",
+        "subtle_wrong": "Keep the local displayName state, but replace the useEffect with a useMemo that recomputes it: `const displayName = useMemo(() => user.name, [user]);` then still call `setDisplayName` from a small effect that only runs when the memoized value changes. This avoids the extra render-then-sync flash on unrelated user field changes while keeping the same displayName state shape the rest of the component already relies on."
+      }
+    },
+    {
+      "id": "key-as-index",
+      "prompt": "I'm rendering a filterable list of todo items with `<TodoItem key={index} .../>` inside a .map. Is that ok?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer says using the array index as key is not safe for a filterable list, because filtering changes which items occupy which index, which corrupts React's identity tracking for local component state, focus, and animation across the filter change. It recommends replacing `index` with a stable, data-derived key such as the item's own `id`.",
+          "pass_criteria": [
+            "States that index-as-key is a problem specifically because this list is filterable (filtering changes which item sits at which index, so React's per-index identity tracking corrupts local state, focus, or animation across a filter change) — a generic 'index keys are bad practice' without tying it to filtering does not satisfy this.",
+            "Shows or names the concrete replacement key (the item's own stable id, e.g. `key={todo.id}`), not just 'use a stable key'."
+          ],
+          "fail_criteria": [
+            "Says using the array index as key is fine/acceptable for this filterable list."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "No, that's not safe here — the list is filterable, which means the mapping between index and actual todo item changes whenever the filter changes: item that was at index 2 might now be at index 0 after some items get filtered out. React uses the key to match up component instances across renders, so when the index-to-item mapping shifts, React thinks the item at a given index is 'the same' component even though it's now backing a different todo, which corrupts any local state that TodoItem holds (an open edit field, an in-progress checkbox animation, input focus) — it stays attached to the index/position instead of following the actual item. Use each todo's own stable identifier instead: `key={todo.id}` (assuming your todo objects have an id field). That keeps each TodoItem's identity tied to the actual data it represents regardless of how filtering reorders or removes items around it.",
+        "known_wrong": "That's totally fine — using the array index for key is standard practice and works well as long as you're not doing drag-and-drop reordering of the list. Since this is just a filter (items are hidden/shown, not manually reordered by the user), the index key won't cause any real problems; React will just re-render the visible items in their new positions and that's it. I wouldn't worry about switching to an id-based key unless you start seeing actual visual glitches.",
+        "vague": "Using the index as key isn't ideal for a list that can be filtered — better to use a stable key instead.",
+        "subtle_wrong": "Index-as-key is usually fine, and since this is filtering (hiding/showing items) rather than reordering them via drag-and-drop, the relative order of visible items doesn't change, so in practice you likely won't see identity bugs here. If you do notice glitches later — stale input values or animation jumps on a filtered item — that's the signal to switch to `todo.id`, but I wouldn't treat it as a must-fix up front for a simple show/hide filter."
+      },
+      "anti_patterns": [
+        "array index"
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,142 @@
+---
+name: react-testing
+description: "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."
+triggers:
+  - "write a test for this component"
+  - "test this react hook"
+  - "fix this act warning"
+  - "mock the api call in this component test"
+  - "add react testing library test"
+  - "write a react testing library test covering the loading and error states"
+metadata:
+  origin: authored
+  category: test
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# React testing (React Testing Library)
+
+Write, extend, or fix a React component or hook test using React Testing
+Library on top of the project's own runner (Vitest or Jest). Scoped to
+component-level testing through RTL's user-facing query/interaction model
+— generic JS/TS unit testing with no component under test is
+`ts-js-node`'s testing skill, and end-to-end browser testing (Playwright)
+is a separate tool skill, not this one; see `governance/scout.json` for the
+fork rationale.
+
+## Workflow
+
+### Step 1: Discover the project's test conventions
+
+1. Confirm the runner (`vitest` or `jest`) from `package.json`
+   scripts/deps, and that React Testing Library
+   (`@testing-library/react`, `@testing-library/user-event`) is already a
+   dependency — do not add Enzyme or introduce a second RTL version.
+2. Find the layout: co-located `Component.test.tsx` next to the component,
+   or a mirrored `__tests__` tree. Match whichever the project already
+   uses.
+3. Read 1-2 neighboring component tests for: render-helper conventions (a
+   custom `render` wrapping providers), query style, and how network calls
+   are mocked (MSW handlers, a manual fetch mock, or a mocked API client
+   module).
+
+### Step 2: Plan the states to cover
+
+- Enumerate the component's rendered states: initial/loading, success,
+  error, empty, and each conditional branch a prop or piece of state
+  gates.
+- For a form, cover: valid submit, validation error shown, pending state
+  during submit, and the post-submit result (including an optimistic
+  update if the component uses `useOptimistic`).
+- For a custom hook with logic worth testing standalone, plan a
+  `renderHook` test instead of mounting a throwaway component.
+
+### Step 3: Write
+
+1. Query by role/label/text -- literally `getByRole(...)` (not
+   `getAllByRole` for a single element you expect exactly one of),
+   `getByLabelText`, `getByText`; use `data-testid` only when no
+   accessible query exists.
+2. Drive interaction with `@testing-library/user-event`
+   (`userEvent.setup()` then `.click`/`.type`/`.tab`), not `fireEvent`,
+   unless the project's pinned `user-event` major cannot express it. Every
+   click/type/submit interaction in a generated test goes through
+   `userEvent`, never `fireEvent.click`/`fireEvent.change` as the
+   click/type mechanism.
+
+   A submit-and-see-an-error test looks like this:
+   ```tsx
+   const user = userEvent.setup();
+   render(<LoginForm />);
+   await user.click(screen.getByRole("button", { name: /submit/i }));
+   expect(await screen.findByText(/password is required/i)).toBeInTheDocument();
+   ```
+3. Wait for async UI with `findBy*` or `waitFor` — never a manual
+   `setTimeout`.
+4. Mock network calls at the request boundary (an MSW handler, or the
+   project's existing equivalent), not by mocking the component's own
+   data-fetching function — a boundary mock still exercises the real
+   fetch/parse/error path.
+5. Assert on rendered output and accessible state (text, role, `aria-*`),
+   never on component internals, instance fields, or a snapshot of
+   private props.
+
+### Step 4: Run and fix
+
+```bash
+keryx test run --changed --strict
+```
+
+`src/testing/service.ts` detects the project's own configured runner — do
+not hard-code `vitest`/`jest` flags beyond what Step 1 already found. On a
+project with no keryx testing config, run the project's own configured
+test command instead.
+
+Fix failing tests (max 3 iterations) — fix the test, not the component
+under test. An `act` warning means a state update escaped RTL's async
+query wrapping; switch to the matching `findBy*`/`waitFor`, do not silence
+the console.
+
+### Step 5: Report
+
+```
+Generated: src/components/UserCard.test.tsx
+  - 6 test cases (loading/success/error/empty + 2 interaction), all passing
+```
+
+## Rules
+
+- ALWAYS query the way a user or assistive technology would (role/label/
+  text) before falling back to `data-testid`.
+- ALWAYS mock network at the request boundary, not the component's
+  internal fetch wrapper.
+- NEVER modify the component under test to make a test pass — file it as a
+  separate implementation change (`react-implementation`) instead.
+- NEVER replace `findBy*`/`waitFor` with a fixed `setTimeout`/`sleep`.
+- If no RTL is configured, suggest adding it; do not add it unasked.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll just grab it with a testid, querying by role is fiddly" | A `data-testid` fallback used by default stops the test from verifying the component is actually accessible; reach for it only when no accessible query exists |
+| "This act warning is noisy, I'll wrap it in act() and move on" | An `act` warning usually means the test is not awaiting the right query; wrapping in `act` by hand without awaiting the real async work hides a real race instead of fixing it |
+| "The test keeps failing on the loading state, I'll mock the component's fetch helper directly" | Mocking the internal helper skips the real request/parse/error-handling code path; mock at the network boundary (MSW or equivalent) instead |
+| "Still red after three iterations; I'll change the component's markup to match the test" | This skill writes test files only — changing markup mid-test-authoring to force a pass is an unreviewed implementation change hiding as a test fix |
+| "I'll snapshot the whole rendered tree, it's faster than writing assertions" | A full-tree snapshot passes on any change including regressions, and fails on cosmetic changes that carry no behavior signal — assert on the specific rendered output instead |
+
+## Verification
+
+Do not report the work done until all of the following hold:
+
+- The test file sits at the project's own convention path, matching the
+  query/mocking style read in Step 1.
+- Every state enumerated in Step 2 has a corresponding passing test, or
+  the report says why one is missing.
+- No test reaches into component internals or asserts on a private prop.
+- `keryx test run --changed --strict` — or the project's own discovered
+  test command — exits 0 with every generated test passing.
+- `git status` shows only test files (and a shared test-render helper, if
+  touched) added or modified; no component source under test changed.