@mrciphersmith/keryx 0.3.0 → 0.3.2

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

@@ -0,0 +1,149 @@
+---
+name: mobx-store-implementation
+description: "Use when writing or extending a MobX store: adding observable state, actions, computed getters, or reactions (autorun/reaction/when), wiring a store into React via observer and a context hook, or fixing a component that stops re-rendering after a store change. Applies the makeObservable/action/runInAction/observer shape and the store's dispose lifecycle. Not for reviewing an already-written store's structure (use code-mobx-store-review) and not for plain React state/props work with no MobX involved (use react-implementation)."
+triggers:
+  - "add a new observable field to this MobX store"
+  - "write a MobX action for this store"
+  - "wire this store up with observer and a context hook"
+  - "this component doesn't re-render when the store changes"
+  - "add a computed getter to this store"
+  - "set up a reaction that disposes when the store unmounts"
+  - "create a new MobX store for this feature"
+  - "make this async store method update state correctly"
+metadata:
+  origin: authored
+  category: implement
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# MobX store implementation
+
+Write or extend a MobX store: observable state, actions, computed
+getters, reactions, and the React wiring (`observer` + context hook) that
+connects it to components. See `rules/coding-style.mdc` for the store
+shape and `rules/patterns.mdc` for the async-action and reaction-disposal
+patterns this skill applies.
+
+## Scope
+
+This skill is for **authoring** store code — a new store, a new
+observable/action/computed on an existing store, a new reaction, or the
+`observer`/context wiring that exposes a store to components. It is not
+for auditing an already-written store's structure or accessibility
+modifiers (`code-mobx-store-review` does that), and it does not cover
+plain React component work that touches no MobX API.
+
+## Workflow
+
+### Step 1: Find the project's own store conventions
+
+Before writing anything, look at 1-2 existing stores in the project (or
+`rules/coding-style.mdc`'s minimal template if none exist yet) for:
+
+- whether the project uses `makeObservable` with explicit annotations or
+  `makeAutoObservable`,
+- the store's file/class naming (`xyz.store.ts` / `XyzStore`),
+- whether stores are exposed via React context + hook, a DI container, or
+  a module singleton,
+- the project's `enforceActions` setting (check the `configure(...)` call,
+  usually in an app-entry or test-setup file) — it determines whether a
+  mutation outside an action throws or only warns.
+
+Match the existing convention; do not introduce a second store-wiring
+style into a codebase that already has one.
+
+### Step 2: Model the state
+
+- Put state that the UI reads and that can change over time on
+  `@observable` (or the appropriate variant — `.ref`/`.shallow`/`.struct`,
+  see `rules/coding-style.mdc`) fields, not in a component's `useState`.
+- Put anything derivable purely from other observable fields on a
+  `@computed get` accessor instead of storing it separately and keeping
+  it in sync by hand.
+- Keep injected dependencies (services, sibling stores) as
+  `private readonly` constructor parameters, not observable.
+
+### Step 3: Write the actions
+
+- Every method that mutates state gets `@action` (private orchestration)
+  or `@action.bound` (public, UI-invoked). A public async action stays
+  thin: guard check, then delegate to a `private async` method that does
+  the real work (see `rules/patterns.mdc`'s async-action shape).
+- Wrap every state mutation that happens after an `await` in
+  `runInAction(() => { ... })`. Reach for `flow` instead only when a
+  store has many sequential-await actions and the repeated
+  `runInAction` blocks are genuinely the dominant noise in the file.
+- Add an equality guard (`if (value !== current)`) before any mutation
+  that could re-trigger a reaction feeding back into the same store from
+  another store, per `rules/patterns.mdc`.
+
+### Step 4: Wire reactions, if the store needs one
+
+- Create `autorun`/`reaction`/`when` in the constructor or an `init()`,
+  push the returned disposer into the store's `disposers` array, and call
+  every disposer in `dispose()`.
+- Prefer `reaction(() => selector, handler)` over `autorun` when the
+  effect should respond to one specific value, not everything the
+  handler body happens to read.
+- Never start a raw `autorun`/`reaction` inside a component's render
+  body; start it in `useEffect` (with cleanup) if it must live in the
+  component rather than the store.
+
+### Step 5: Wire the store into React
+
+- Expose the store through a typed `createContext<XyzStore | null>(null)`
+  and a `useXyzStore()` hook that throws if the context is unset — do not
+  export a bare module-level store instance for components to import
+  directly unless that already is the project's convention.
+- Wrap every component that reads store state in `observer` from
+  `mobx-react-lite`. If a component "doesn't re-render", check this
+  first: a missing `observer` wrapper is the most common cause, followed
+  by reading the observable value too early (destructured far from where
+  it's rendered) breaking fine-grained tracking.
+
+### Step 6: Verify
+
+Run the project's type-check, lint, and store/component tests; see
+Verification below for the exact bar.
+
+## Rules
+
+- Follow `rules/coding-style.mdc` for store shape, decorators, and
+  observable-collection typing.
+- Follow `rules/patterns.mdc` for the async-action shape, `flow`,
+  reaction disposal, and the View↔Store boundary.
+- ALWAYS wrap a post-`await` state mutation in `runInAction`; NEVER leave
+  it as a bare assignment relying on `enforceActions` being off.
+- ALWAYS wrap a component that reads observable state in `observer`;
+  NEVER assume a plain function component will re-render on a store
+  change just because it received the store as a prop.
+- NEVER mutate observable state from inside a `@computed` getter.
+- NEVER create a reaction (`autorun`/`reaction`/`when`) without storing
+  and later calling its disposer.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll just mutate `this.items` right after the `await`, it's simpler than wrapping it" | Outside an action, that mutation either throws under `enforceActions` or silently fails to notify observers depending on config — wrap it in `runInAction` |
+| "This component isn't re-rendering, I'll add a `key` prop / force a remount" | A forced remount papers over the real cause; check for a missing `observer` wrapper or a value read too early first |
+| "I'll skip the disposer, the store lives for the app's whole lifetime anyway" | Even a long-lived store's undisposed reactions keep running against stale data on route/user change; store and call the disposer |
+| "I'll compute this inline in the component instead of a `@computed`, it's just one line" | A component-side recomputation runs on every render and drifts from the store's own reactivity graph the moment two components need the same derived value |
+
+## Verification
+
+Do not report the store/wiring done until all of the following hold:
+
+- The project's type-check (e.g. `tsc --noEmit`) exits 0.
+- Every action that mutates state after an `await` does so inside
+  `runInAction` (or is a `flow` generator).
+- Every component reading the new/changed observable state is wrapped in
+  `observer`.
+- Every `autorun`/`reaction`/`when` created has its disposer stored and
+  called in `dispose()`.
+- The project's lint (including `@typescript-eslint/explicit-member-accessibility`
+  if configured) passes with no new suppressions.
+- Existing store/component tests still pass; a new observable/action has
+  at least one test exercising it (see `rules/testing.mdc`).

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

@@ -0,0 +1,74 @@
+{
+  "triggers": {
+    "positive": [
+      "Whichever item the user clicks should stay highlighted everywhere it's shown on the page, even after they navigate away and back -- what's the cleanest way to track that in MobX?",
+      "I have an async method on this MobX store that hits an API and then updates a few fields -- what's the right way to write that so the state updates correctly?",
+      "I've got a new MobX store -- what's the right way to make it available to my React components so they can read from it and re-render when it changes?",
+      "This component isn't re-rendering when the store's items array changes, help me fix the wiring",
+      "The order total should be derived from the line items in this MobX store rather than kept in sync by hand",
+      "This store needs to log something every time a value on it changes, but only while the component using it is actually mounted -- how do I set that up in MobX?",
+      "Our settings panel needs its own MobX store that tracks loading and error while it saves",
+      "Convert this async store method so the post-await mutations are wrapped correctly"
+    ],
+    "negative": [
+      "Review this MobX store for accessibility-modifier and method-ordering issues",
+      "Write a test that waits for this store's async fetchItems action to resolve before asserting",
+      "Add client-side form validation and inline error messages to this plain React form, no state library involved",
+      "Fix this tsc error: Property 'total' does not exist on type 'OrderDraft'",
+      "Add a new Pinia store action for saving user preferences",
+      "Run the project's lint and type-check scripts and report every failure"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "wrap-post-await-mutation",
+      "prompt": "I have this MobX action:\n\n```ts\nasync fetchItems() {\n  this.loading = true;\n  const items = await this.service.getAll();\n  this.items = items;\n  this.loading = false;\n}\n```\n\nWhat needs to change so it works correctly under MobX's enforceActions?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer explains that code after an await runs outside the original action's transaction, and fixes it by wrapping every state mutation that happens after the await (this.items = items and this.loading = false) inside runInAction, showing the corrected code rather than only describing the change.",
+          "pass_criteria": [
+            "Shows the corrected code wrapping the post-await assignments (this.items = items and this.loading = false) inside runInAction(() => { ... }), or restructures the method as a flow generator that achieves the same effect",
+            "States that code after an await runs outside the original action's own transaction, which is why the bare assignments need to re-enter via runInAction (or flow)"
+          ],
+          "fail_criteria": [
+            "Recommends disabling or loosening enforceActions (e.g. configuring it to 'never' or 'never' equivalent) instead of wrapping the post-await mutations in runInAction -- mentioning that only to warn against it is not a failure",
+            "Leaves this.items = items or this.loading = false as bare, unwrapped assignments after the await with no runInAction or flow restructuring"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "The problem is that everything after the `await` runs outside the action's original transaction, so MobX no longer treats those assignments as happening inside an action -- under enforceActions that throws, and even without it the reaction system can miss the update. Wrap the post-await mutations in runInAction:\n\n```ts\nasync fetchItems() {\n  runInAction(() => {\n    this.loading = true;\n  });\n  const items = await this.service.getAll();\n  runInAction(() => {\n    this.items = items;\n    this.loading = false;\n  });\n}\n```\n\nAlternatively, rewrite it as a `flow` generator, which keeps the whole body inside one action and needs no runInAction at all:\n\n```ts\nfetchItems = flow(function* (this: ItemStore) {\n  this.loading = true;\n  this.items = yield this.service.getAll();\n  this.loading = false;\n});\n```\n\nEither way, re-run the type-check and confirm no enforceActions warning/throw fires when this action runs.",
+        "known_wrong": "Easiest fix: just set `configure({ enforceActions: 'never' })` in your app setup so MobX stops complaining about mutations outside actions. Then you can leave fetchItems exactly as it is -- the assignments after the await will still update the observable fields and trigger reactions, MobX just won't enforce the action-boundary rule anymore, which saves you from having to wrap anything in runInAction.",
+        "vague": "You should make sure the state updates after the await happen inside an action so MobX can properly track them, otherwise you might run into issues with enforceActions.",
+        "subtle_wrong": "The important part is that `this.items` gets set correctly, so I wrapped just that one in runInAction: `runInAction(() => { this.items = items; })`. I left `this.loading = false` as a plain assignment right after since it's just a boolean flag and not the actual data -- that keeps the change minimal and the loading indicator still clears in practice even without wrapping it."
+      }
+    },
+    {
+      "id": "component-not-rerendering",
+      "prompt": "This component reads `store.items.length` in its JSX but never updates when items change:\n\n```tsx\nfunction ItemList({ store }: { store: ItemStore }) {\n  return <div>{store.items.length} items</div>;\n}\n```\n\nWhat's wrong and how do I fix it?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer identifies that ItemList itself is not wrapped in observer from mobx-react-lite, which is why it renders once and never reacts to store.items changing, and fixes it by wrapping this specific component in observer.",
+          "pass_criteria": [
+            "States that ItemList is missing the observer wrapper (mobx-react-lite) around the component that actually reads store.items, and that this is why it stops updating after the first render",
+            "Shows the corrected code with ItemList itself wrapped in observer (e.g. `const ItemList = observer(({ store }: { store: ItemStore }) => <div>{store.items.length} items</div>);`)"
+          ],
+          "fail_criteria": [
+            "Recommends forcing a re-render through a changing key prop, forceUpdate, or mirroring store.items.length into a useState/useEffect pair instead of wrapping ItemList in observer -- mentioning that only to warn against it is not a failure",
+            "Wraps only a parent/ancestor component in observer while leaving ItemList itself unwrapped, and claims that is sufficient for ItemList's own re-render"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "ItemList reads `store.items.length` directly, but it's a plain function component -- nothing tells MobX to track its render and re-run it when items changes. Wrap ItemList itself in observer from mobx-react-lite:\n\n```tsx\nimport { observer } from \"mobx-react-lite\";\n\nconst ItemList = observer(({ store }: { store: ItemStore }) => (\n  <div>{store.items.length} items</div>\n));\n```\n\nobserver makes MobX track every observable read during that component's render and re-render it specifically when one of those observables changes. Since ItemList is the component doing the read, it has to be the one wrapped -- wrapping some ancestor further up the tree would not make ItemList itself re-render on its own.",
+        "known_wrong": "Simplest fix: pass a changing key prop from the parent, like `<ItemList key={store.items.length} store={store} />`, so React remounts ItemList whenever the length changes. That forces a fresh render with the current value without having to touch MobX wiring at all.",
+        "vague": "Something about how the component is hooked up to the store isn't quite right -- you probably need to set up the MobX integration for this component so it responds to changes.",
+        "subtle_wrong": "The fix is to wrap the parent component that renders ItemList in observer, since that's where store gets passed down from -- once the parent is observed, MobX should propagate the re-render down to ItemList whenever store.items changes, so I left ItemList itself as a plain function component."
+      }
+    }
+  ]
+}

package/src/gdskills/bundled/stacks/nestjs/agent-refs.json

@@ -0,0 +1,4 @@
+{
+  "agents": [],
+  "note": "Demoted from stable (R1 review, PR #719, final honest gate re-run after fixing review findings): nestjs-implementation's trigger-positive-5 (the exception-filter prompt) no longer routes correctly (TP 6/7) once its positive was reworded away from naming the internal APP_FILTER token to describe the goal/symptom only -- an honest, accepted regression per the review's own instruction not to re-stuff the prompt to force a pass. nestjs-testing and nestjs-build-fix both still pass cleanly; nestjs-implementation alone fails the pack. No generated agent pair; the earlier nestjs-build-fixer.md is removed."
+}