@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/react-patterns/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: react-patterns
+description: React component design rules for function components and hooks, covering where state should live, the Rules of Hooks, effects used only to synchronise with external systems, data fetching without race conditions, controlled and uncontrolled forms with React 19 actions, error boundaries, choosing context versus a state library, and accessible markup. Use when building or restructuring React components, deciding where a piece of state belongs, writing or removing a useEffect, wiring up a form, or picking between context, Zustand, Redux or a query cache.
+license: MIT
+compatibility: Any Agent Skills host. Applies to React 18 and 19 with any bundler or framework (Vite, Next.js, Remix, React Router). Needs Node.js and the project's package manager to run lint and tests.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/requires: "node"
+  kete-loom/owner: "Kete-org"
+---
+
+# React patterns
+
+Write components that are pure during render, keep state as small and as local as possible, and treat effects as an escape hatch. For Next.js server/client concerns use the `nextjs-patterns` skill; for render speed use `react-performance`.
+
+## 0. Before you change anything
+
+1. Check the React version in `package.json` (`react`, `react-dom`). React 19 APIs (`useActionState`, `useOptimistic`, `use`, form `action` props, `ref` as a prop) don't exist in 18.
+2. Check what the project already uses for server state (TanStack Query, SWR, RTK Query, Apollo, framework loaders) and client state (context, Zustand, Redux, Jotai). Follow it. Don't add a second library for the same job.
+3. Check lint config for `eslint-plugin-react-hooks` (`rules-of-hooks`, `exhaustive-deps`). If it's missing, tell the user; don't silently add it.
+
+## 1. Where state lives
+
+Decide in this order and stop at the first that fits:
+
+1. **Derive it.** If a value can be computed from props or other state, compute it during render. Never mirror props into state (`useState(props.x)` plus an effect to sync it).
+2. **Local `useState`/`useReducer`** in the lowest component that needs it. Use `useReducer` when several fields change together or the next state depends on an action type.
+3. **Lift** to the closest common parent when two siblings need it.
+4. **URL** (search params, path) for anything that should survive reload or be shareable: filters, tabs, pagination, selected item.
+5. **Server-state cache** (the project's query library or framework loader) for data owned by the backend. Never copy fetched data into a global store by hand.
+6. **Context** for values many distant components read and that change rarely: theme, locale, current user, a feature-flag client.
+7. **A state library** only when client state is large, updated from many places, and context would re-render too much.
+
+Rules:
+- Store the minimum: an `id`, not a copy of the selected object.
+- Reset state with a `key` (`<Profile key={userId} />`), not with an effect.
+- Put the state setter and value in separate contexts if consumers only need one, or memoise the context value object.
+
+## 2. Rules of Hooks
+
+- Call hooks only at the top level of a component or a custom hook. No hooks inside conditions, loops, nested functions, `try` blocks or after an early `return`.
+- Custom hooks start with `use` and may call other hooks. A function that calls no hooks is not a hook; don't prefix it.
+- Never call a component as a function (`Row()`); render it (`<Row />`).
+- Never define a component inside another component's body. It remounts every render and loses state.
+- Render must be pure: no mutation of props, state or module variables, no `Math.random()`/`Date.now()` driving output without a stable source, no reading or writing `ref.current` during render (except lazy init).
+
+## 3. Effects: synchronisation only
+
+An effect is for keeping React in sync with something outside React: a subscription, a browser API, a non-React widget, a websocket. Before writing `useEffect`, check whether you need it:
+
+| You want to... | Do this instead |
+|---|---|
+| Compute a value from props/state | Compute during render (memoise only if measured slow) |
+| Respond to a click or submit | Put the logic in the event handler |
+| Reset state when a prop changes | Change the `key` |
+| Adjust part of state when a prop changes | Derive it, or store the previous prop and compare during render |
+| Notify a parent of a change | Call the parent's callback in the same handler that changed state |
+| Fetch data | Use the project's data library or framework loader (section 4) |
+
+When you do write one:
+1. List every reactive value it reads in the dependency array. Never suppress `exhaustive-deps`; restructure instead (move the function inside the effect, use an updater `setX(x => x + 1)`, or move non-reactive logic to `useEffectEvent` on React 19.2+).
+2. Return a cleanup that undoes the setup: unsubscribe, `clearInterval`, `controller.abort()`, `disconnect()`.
+3. Expect it to run twice in development under `<StrictMode>`. If that breaks something, the cleanup is wrong; don't remove StrictMode.
+4. Don't call `setState` synchronously in the effect body just to derive state; that is section 1, rule 1.
+
+## 4. Data fetching
+
+Prefer, in order: the framework's loader or a Server Component (Next.js, Remix, React Router), then the project's query library, then a hand-rolled effect.
+
+If you must fetch in an effect, guard against races and unmounts:
+
+```tsx
+useEffect(() => {
+  const controller = new AbortController();
+  setStatus("loading");
+  fetch(`/api/users/${id}`, { signal: controller.signal })
+    .then((r) => { if (!r.ok) throw new Error(`HTTP ${r.status}`); return r.json(); })
+    .then((data) => { setUser(data); setStatus("done"); })
+    .catch((e) => { if (e.name !== "AbortError") { setError(e); setStatus("error"); } });
+  return () => controller.abort();
+}, [id]);
+```
+
+- Model loading, error and empty states explicitly; never render `data.items.map` before data exists.
+- Start independent requests in parallel (`Promise.all`, or sibling components each with their own query), not one after another.
+- With `use(promise)` on React 19, create the promise outside render (in a loader, a Server Component or a cache) and wrap the reader in `<Suspense>`. A promise created during render is recreated every render.
+
+## 5. Forms
+
+- **Uncontrolled + `FormData`** is the default for submit-only forms: `<form action={fn}>` on React 19, or `onSubmit` with `new FormData(e.currentTarget)` on 18.
+- **Controlled inputs** (`value` + `onChange`) only when you need the value on every keystroke: live validation, formatting, dependent fields.
+- Never switch an input between controlled and uncontrolled; initialise with `""`, not `undefined`.
+- React 19: `useActionState(action, initialState)` returns `[state, formAction, isPending]` for results and errors; `useFormStatus()` (from `react-dom`) reads pending state inside a child of the `<form>`; `useOptimistic` shows the expected result while the action runs.
+- For large forms the project may use React Hook Form or similar; follow it.
+- Validate on the server too. Client validation is UX, not security.
+- Every input has a `<label htmlFor>` (or wraps the input); errors are linked with `aria-describedby` and announced (`role="alert"` or `aria-live="polite"`).
+- Disable the submit button while pending, and keep it focusable.
+
+## 6. Error boundaries
+
+- Error boundaries catch errors thrown during render, in lifecycle methods and in constructors below them. They do **not** catch errors in event handlers, async code (timers, promises after an `await`), or the boundary itself.
+- There is no hook equivalent: write a class with `static getDerivedStateFromError` and `componentDidCatch`, or use the project's `react-error-boundary` if it's installed. Frameworks may provide their own (`error.tsx` in Next.js).
+- Place boundaries around independent regions (a widget, a route segment), not just once at the root. Give each a fallback with a retry that resets it (`resetKeys` or a changed `key`).
+- Handle event-handler and async errors with `try/catch` and state; to route them into a boundary, set state and rethrow during render.
+- Report the error in `componentDidCatch` (or the root's `onCaughtError`/`onUncaughtError` on React 19) to the project's logger.
+
+## 7. Context vs state libraries
+
+- Context is a dependency-injection mechanism, not a store: every consumer re-renders when the value identity changes.
+- Split contexts by update frequency. Never put fast-changing values (mouse position, form text) in a widely consumed context.
+- Server data belongs in a query cache, not context or Redux.
+- Pick a store (Zustand, Redux Toolkit, Jotai) only for shared, frequently updated client state, and use selectors so components subscribe to slices.
+
+## 8. Accessibility basics
+
+- Use the right element: `<button>` for actions, `<a href>` for navigation, `<label>` for inputs, headings in order. A `<div onClick>` is not a button.
+- Every image has `alt` (`alt=""` if decorative). Icon-only buttons have `aria-label`.
+- Keyboard: everything clickable is reachable with Tab and works with Enter/Space; focus is visible; dialogs trap focus and return it on close (prefer `<dialog>` or the project's headless UI library).
+- After route changes or async updates, move focus or announce the change.
+- Lists use stable, unique `key`s from the data (an id), never the array index when items can be reordered, inserted or removed.
+- For full audits use the `web-accessibility` skill.
+
+## Never
+
+- Never mutate state or props in place (`arr.push`, `obj.x = 1`); create new values.
+- Never suppress `react-hooks` lint rules to make a warning go away.
+- Never put secrets or tokens in client code or `localStorage` because "it's only the frontend".
+- Never use `dangerouslySetInnerHTML` with unsanitised input.
+
+## Stop and ask the user
+
+- Before adding a new state, data or form library.
+- Before converting many components between controlled and uncontrolled, or between class and function components, beyond the task.
+- When the expected behaviour on error, empty or loading states isn't specified.
+
+## Report back
+
+End with: components changed, where each new piece of state lives and why, effects added or removed, the lint and test commands you ran with results, and anything not checked (for example "did not test with a screen reader").

package/skills/react-patterns/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Should this filter state live in the parent component, the URL, or a context?",
+    "I have a useEffect that copies props into state and it keeps getting out of sync, how should I restructure it?",
+    "Build a signup form component in React with validation errors shown under each field",
+    "Our dashboard crashes completely when one widget throws, add error boundaries properly",
+    "Is it worth adding Zustand or should I just use React context for the cart state?",
+    "Write a custom hook that subscribes to window resize and cleans up correctly"
+  ],
+  "should_not_trigger": [
+    "The product list re-renders 200 times when I type in the search box, profile it and speed it up",
+    "Should this Next.js page be a server component or a client component?",
+    "Review this React pull request for stale closures and hook violations",
+    "Set up revalidateTag caching for the blog posts in my App Router app",
+    "Write Playwright end-to-end tests for the checkout flow",
+    "Make my React Native FlatList scroll smoothly on Android"
+  ]
+}

package/skills/react-performance/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: react-performance
+description: Measure-first workflow for slow React UIs - profile renders with React DevTools and the Profiler API, cut wasted re-renders with memo, useMemo and useCallback only where the profile shows a win (or let React Compiler do it), virtualise long lists, split code with lazy and Suspense, remove request waterfalls, and shrink the JavaScript bundle. Use when a React or Next.js screen feels laggy, typing or scrolling stutters, a component re-renders too often, Interaction to Next Paint is poor, or the client bundle has grown too big.
+license: MIT
+compatibility: Any Agent Skills host. Applies to React 18 and 19 in any framework. Needs Node.js, the project's package manager and a browser with React DevTools for profiling.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "node"
+  kete-loom/owner: "Kete-org"
+---
+
+# React performance
+
+No optimisation without a measurement before and after. Most React slowness comes from a few causes: rendering too much, rendering too often, loading too much JavaScript, or waiting on requests one after another. Component design rules live in `react-patterns`; Next.js caching and server/client splits in `nextjs-patterns`; Core Web Vitals and non-React page speed in `web-performance`.
+
+## 1. Define the problem
+
+1. Get a concrete symptom from the user: which screen, which interaction (typing, scrolling, opening a panel, first load), on what device. If it's vague, ask.
+2. Classify it:
+   - **Interaction is slow** (input lag, janky scroll): render cost. Go to 2.
+   - **First load is slow** (blank screen, late content): bundle or waterfalls. Go to 5 and 6.
+3. Measure in a production build (`npm run build` then the project's preview/start command). Development mode and StrictMode double-render and are several times slower; never judge speed there.
+
+## 2. Measure renders
+
+1. React DevTools → Profiler: record the slow interaction, then read the flame graph and ranked chart. Note the slowest commits, which components rendered, and "Why did this render?" (enable "Record why each component rendered while profiling" in settings).
+2. Turn on "Highlight updates when components render" to see what re-renders while you interact.
+3. Use the browser Performance panel with CPU throttling (4x or 6x) for long tasks over 50 ms and layout/paint cost that DevTools won't show.
+4. For numbers you can compare in code or CI, wrap the subtree in `<Profiler id="Grid" onRender={(id, phase, actualDuration, baseDuration) => ...}>`. `actualDuration` is time spent rendering this commit; `baseDuration` estimates a full re-render without memoisation. Profiling a production build needs the profiling build of `react-dom` (see the React docs for your bundler); `<Profiler>` adds overhead, so remove it or gate it after measuring.
+5. Write down the baseline: commit duration and count for the interaction, or long-task total. You'll compare against it.
+
+## 3. Fix rendering cost, cheapest first
+
+Work down this list and re-measure after each change:
+
+1. **Move state down.** If typing in one input re-renders the whole page, the state is too high. Move it into the component that uses it.
+2. **Lift content up (children as props).** A parent with fast-changing state that renders `{children}` doesn't re-render those children.
+3. **Split contexts.** One context with a frequently changing value re-renders every consumer. Split by update rate, or move fast state to a store with selectors.
+4. **Stop recreating expensive work.** `useMemo` for a computation the profile shows is slow (rule of thumb: over ~1 ms per render) or for an object/array passed to a memoised child or an effect dependency.
+5. **Skip unchanged subtrees.** `React.memo(Component)` on a component that renders often with the same props and is costly to render. It only helps if every prop is stable: wrap callbacks in `useCallback`, objects in `useMemo`, or pass primitives.
+6. **Defer non-urgent updates.** `useDeferredValue(query)` for a slow results list behind a fast input; `startTransition(() => setFilter(x))` for updates that can be interrupted.
+7. **Virtualise long lists** (section 4).
+
+Memoisation rules:
+- Don't wrap everything. `memo`/`useMemo`/`useCallback` cost memory and comparisons; unprofiled memoisation is noise.
+- A memoised child receiving `onClick={() => ...}` or `style={{...}}` inline never skips; fix the prop, not the child.
+- Keys: stable ids, never `Math.random()` or array index for lists that change. A changing key remounts the subtree, which is far slower than a re-render.
+- If the project has React Compiler enabled (`babel-plugin-react-compiler`, or `reactCompiler: true` in Next.js 16, `experimental.reactCompiler` in 15), it memoises automatically. Don't add manual `useMemo`/`useCallback` to compiled code unless a profile shows it's still needed; do keep components pure so the compiler doesn't skip them (the `react-hooks` lint compiler rules report why).
+- Don't enable the compiler as a side effect of a perf fix; ask first.
+
+## 4. Long lists and big tables
+
+- Over a few hundred rows, or rows that are expensive, render only what's visible. Use the library already in the project; otherwise `@tanstack/react-virtual` or `react-window`.
+- Give rows a fixed or measured height; variable heights need the library's measurement API.
+- Keep row components memoised with stable props, and keep scroll position, focus and keyboard navigation working. Check that Ctrl+F and screen readers are acceptable for the use case, or paginate instead.
+- For simple long pages, CSS `content-visibility: auto` with `contain-intrinsic-size` can be enough without a library.
+
+## 5. Waterfalls
+
+A waterfall is request B starting only after request A finishes when it didn't need A.
+
+1. Open the Network panel (throttled to "Fast 4G") and look for staircase-shaped requests.
+2. Common causes and fixes:
+   - Parent fetches, renders child, child fetches: hoist both fetches to the route loader or Server Component and start them together (`Promise.all`), or prefetch.
+   - Sequential `await`s in one function for independent data: start promises first, await later.
+   - `React.lazy` component that then fetches its data: start the data request in parallel with loading the code (route loader, prefetch on hover/intent).
+   - A `<Suspense>` boundary around each sibling that each suspends in turn: put siblings that load together under one boundary, separate ones under their own.
+3. In Next.js, fetch on the server and stream with `<Suspense>`; see `nextjs-patterns`.
+
+## 6. Bundle size and code splitting
+
+1. Measure what ships:
+   - Vite/Rollup: `rollup-plugin-visualizer`.
+   - webpack: `webpack-bundle-analyzer`.
+   - Next.js with Turbopack (16.1+): `npx next analyze` (`--output` writes to `.next/diagnostics/analyze` for before/after diffs). Next.js on webpack: `@next/bundle-analyzer` wrapped in `next.config` with `enabled: process.env.ANALYZE === "true"`, then `ANALYZE=true npm run build`.
+   - Any build with source maps: `source-map-explorer`.
+2. Look for: a large dependency used for one function (date, lodash, icon or chart libraries), duplicates of the same package at two versions, server-only or test code in the client bundle, and polyfills you don't need.
+3. Fix, in order: import only what you use (`import debounce from "lodash/debounce"`, per-icon imports); replace heavy libraries with platform APIs (`Intl.DateTimeFormat`, `structuredClone`) or lighter ones (ask before swapping); dedupe versions.
+4. Split by route first, then by heavy, rarely used components (editors, charts, maps, modals): `const Chart = lazy(() => import("./Chart"))` inside `<Suspense fallback>`; in Next.js use `next/dynamic` or keep the component on the server.
+5. Don't split tiny components; each chunk costs a request.
+6. Re-run the analyser and record the size change (gzip/brotli).
+
+## Never
+
+- Never claim a speed-up without before/after numbers from the same build type and device profile.
+- Never measure in development mode.
+- Never suppress `exhaustive-deps` to "stop an effect re-running"; fix the unstable dependency.
+- Never add a virtualisation, state or memo library when moving state or fixing a prop solves it.
+
+## Stop and ask the user
+
+- When the symptom or target (for example "INP under 200 ms on a mid-range Android") isn't stated.
+- Before replacing a dependency, enabling React Compiler, or changing list UX (virtualising, paginating).
+- When the fix needs a design change (removing a feature from a screen, changing data shape on the API).
+
+## Report back
+
+```
+Symptom: <screen + interaction>
+Baseline: <metric, build type, device/throttle>
+Cause: <what the profile showed>
+Change: <files and what changed>
+After: <same metric, same conditions>
+Not checked: <e.g. low-end mobile, Safari>
+```

package/skills/react-performance/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Typing in the search box lags badly because the whole results table re-renders on every keystroke",
+    "Use the React Profiler to find out why my dashboard is slow when I toggle the sidebar",
+    "Our main JS chunk is 1.8 MB, help me code split the React app and find what's bloating it",
+    "Rendering 10,000 rows in this React table freezes the browser, should I virtualise it?",
+    "Is wrapping every component in React.memo and useCallback actually helping or hurting?",
+    "The page loads data in a staircase: user, then orders, then items. Fix the waterfall in our React app"
+  ],
+  "should_not_trigger": [
+    "Should the shopping cart state live in context or in Zustand?",
+    "How do I write a server action that updates a profile in Next.js App Router?",
+    "Benchmark these two sorting functions in Node and tell me which is faster",
+    "Improve the Lighthouse SEO score and meta tags on our marketing site",
+    "Review this React PR for hook rule violations and missing keys",
+    "Our Postgres queries are slow, add the right indexes"
+  ]
+}

package/skills/redis-patterns/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: redis-patterns
+description: Redis and Valkey design for application code, covering which data structure fits each job, key naming and TTLs, cache-aside with stampede protection, single-instance locks and their limits, Streams consumer groups versus pub/sub, and maxmemory, eviction and persistence settings. Use when adding a Redis cache, rate limiter, queue, leaderboard or lock, reviewing Redis keys and commands for memory or latency problems, or choosing eviction and AOF or RDB settings.
+license: MIT
+compatibility: Any Agent Skills host. Commands are Redis protocol and work with redis-cli; examples apply to any client library. Newer commands (hash field TTLs, DELEX) need a recent server, so check the version first.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: data
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "redis-cli"
+  kete-loom/owner: "Kete-org"
+---
+
+# Redis patterns
+
+Use Redis for what it is good at: small, hot, mostly derived data with known access paths. Every key has an owner, a shape and a lifetime. If a design breaks one of the rules below, say so before writing code.
+
+## 0. Before you start
+
+1. Find the client library and how it connects (single node, Sentinel, Cluster, or a managed service). Search the codebase for the client constructor and the connection URL variable.
+2. Find the server version: `redis-cli INFO server` (look at `redis_version`, or `valkey_version` on Valkey). Only use a command if that version has it. The command pages on redis.io list a "since" version.
+3. Decide whether this Redis is a **cache** (losing data is fine) or a **store** (losing data is an incident). **Stop and ask the user** if you can't tell; the eviction and persistence settings depend on it.
+4. Never run `KEYS *`, `FLUSHALL`, `FLUSHDB`, `DEBUG` or `CONFIG SET` against a shared or production instance. Use `SCAN` with `MATCH` and `COUNT` to inspect keys, and ask before any write to a non-local server.
+
+## 1. Pick the data structure by access pattern
+
+| Need | Use | Not |
+|---|---|---|
+| One cached value or counter | String (`SET`/`GET`, `INCR`) | A JSON blob you rewrite to change one field |
+| An object whose fields you read or update separately | Hash (`HSET`, `HGET`, `HINCRBY`) | One key per field |
+| Ranking, time-ordered index, sliding-window limiter | Sorted set (`ZADD`, `ZRANGE ... BYSCORE`, `ZREMRANGEBYSCORE`) | A list you sort in the app |
+| Membership or deduplication | Set (`SADD`, `SISMEMBER`) | A list scanned with `LRANGE` |
+| Approximate unique counts | HyperLogLog (`PFADD`, `PFCOUNT`) | A set holding millions of IDs |
+| A durable work queue with acknowledgement | Stream with a consumer group | A list with `BLPOP` when losing a job matters |
+| Fire-and-forget fan-out to connected clients | Pub/sub | Pub/sub for anything that must not be lost |
+
+Keep each value small, ideally under about 100 KB. Big values and big collections block the single command thread while they are read, written or deleted. Delete big keys with `UNLINK`, not `DEL`, and page through big collections with `HSCAN`, `SSCAN` or `ZSCAN`.
+
+## 2. Key design and TTLs
+
+- Name keys `<app>:<entity>:<id>[:<facet>]`, for example `shop:user:42:cart`. Lower case, colon-separated, no user-controlled text that isn't validated or hashed.
+- Version cache keys when the cached shape changes (`shop:v2:product:9`), so old and new code don't read each other's values during a deploy.
+- **Every cache key gets a TTL when it is written**: `SET key value EX 300`, not `SET` followed by a separate `EXPIRE` that can be skipped if the process dies. A plain `SET` without `KEEPTTL` removes an existing TTL.
+- Add jitter to TTLs (for example 300 seconds plus or minus 10 percent) so keys written together don't expire together.
+- Hash fields can carry their own TTL with `HEXPIRE` on Redis 7.4 and later. On older servers, expire the whole hash or use separate keys.
+- In Redis Cluster, a multi-key command or transaction needs all its keys in one slot. Put the shared part in braces, `shop:{user:42}:cart` and `shop:{user:42}:wishlist`, and only for keys that are really used together, or one slot gets hot.
+
+## 3. Caching
+
+Default to **cache-aside**: read the cache; on a miss, read the source of truth, write the cache with a TTL, return. On a write, update the database first, then **delete** the cache key (don't write the new value into the cache from the write path, which races with concurrent readers).
+
+Protect hot keys from a **stampede** (many requests missing at once and all hitting the database):
+
+1. **Request coalescing in-process**: one in-flight load per key per process.
+2. **A short rebuild lock**: on a miss, `SET lock:<key> <token> NX PX 5000`. The winner rebuilds; others wait briefly and re-read, or serve a stale copy.
+3. **Early refresh**: store the value with a soft expiry inside it and refresh in the background shortly before the hard TTL.
+
+Also cache "not found" for a short TTL so missing IDs don't hammer the database, and never cache errors as values. Tell the user what the staleness window is; if they need read-your-writes, the cache must be deleted in the same request that writes.
+
+## 4. Locks
+
+A lock in Redis is a **lease, not a guarantee**.
+
+- Acquire: `SET lock:<resource> <random-token> NX PX <ttl-ms>`. The token is unique per acquisition.
+- Release only your own lock: compare the token and delete in one atomic step, with a Lua script (`if redis.call("get",KEYS[1]) == ARGV[1] then return redis.call("del",KEYS[1]) else return 0 end`) or `DELEX key IFEQ token` on Redis 8.4 and later. Plain `DEL` can delete another client's lock.
+- Replication is asynchronous, so a failover can hand the same lock to two clients. Clock jumps can too. Redlock (several independent masters) narrows this but doesn't remove it.
+- If two holders at once would corrupt data or move money, **stop and tell the user**: protect the write itself with a fencing token checked by the database (a version column, `UPDATE ... WHERE version = ?`) or use the database's own locks. Use a Redis lock alone only where an occasional overlap is acceptable (deduplicating cron runs, rebuild locks).
+
+## 5. Streams and pub/sub
+
+- Pub/sub delivers only to subscribers connected at that moment, at most once. A disconnect loses messages.
+- For jobs and events that must be processed, use a Stream: `XADD events MAXLEN ~ 100000 * field value`, a group with `XGROUP CREATE events workers $ MKSTREAM`, consumers that `XREADGROUP GROUP workers <consumer> COUNT 10 BLOCK 5000 STREAMS events >`, and `XACK` only after the work is done.
+- Reclaim stuck messages from dead consumers with `XAUTOCLAIM` on a schedule, count deliveries, and move messages that keep failing to a dead-letter stream.
+- Delivery is at least once, so make handlers idempotent.
+- Cap every stream with `MAXLEN` or `MINID` trimming; an untrimmed stream grows until memory runs out.
+
+## 6. Memory, eviction and persistence
+
+Read `references/operations.md` before you change server settings. The short rules:
+
+- Set `maxmemory` below the container or instance limit, leaving room for replication and AOF buffers.
+- A pure cache uses `allkeys-lru` or `allkeys-lfu`. A store uses `noeviction` (the default) and alerts on memory. Don't mix critical keys and cache keys on one instance under a `volatile-*` policy; use two instances.
+- A store needs persistence: AOF with `appendfsync everysec` loses at most about a second on a crash; add RDB snapshots for backups. A pure cache can run with neither.
+- Find slow and large things with `SLOWLOG GET`, `redis-cli --bigkeys`, `redis-cli --memkeys` and `MEMORY USAGE <key>`; these are read-only.
+
+## 7. Atomicity
+
+- Use a single command when one exists (`INCR`, `SET NX`, `ZADD GT`, `GETDEL`).
+- Use `MULTI`/`EXEC` to batch writes atomically. It doesn't roll back a failed command and can't branch on a value read inside it; use `WATCH` for optimistic check-and-set, or a Lua script or Function for read-then-write logic.
+- Keep scripts short: they block every other client while they run.
+- Pipeline independent commands to cut round trips; a pipeline is not atomic.
+
+## Never
+
+- Use Redis as the only copy of data the user can't lose, unless persistence and backups are set up and the user has agreed.
+- Store secrets or personal data without a TTL and a reason.
+- Call `KEYS`, `SMEMBERS`, `HGETALL` or `LRANGE 0 -1` on collections that can grow without bound in a request path.
+- Retry a failed lock acquisition in a tight loop; back off with jitter.
+
+## Report format (when reviewing)
+
+```
+Redis review: <scope>
+Mode: cache | store | mixed (risk)
+Findings:
+1. [severity] <file:line or key pattern>: <problem> → <fix>
+Settings checked: maxmemory, maxmemory-policy, appendonly/appendfsync, save
+Not verified: <anything you could not run or see>
+```

package/skills/redis-patterns/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Add a Redis cache in front of the product lookup and stop the stampede when the key expires",
+    "Our Redis instance keeps getting OOM command not allowed errors, what maxmemory-policy should we use?",
+    "Build a sliding window rate limiter for the login endpoint using Redis sorted sets",
+    "Is SET NX PX safe enough as a distributed lock for our cron jobs in Redis?",
+    "Should I use Redis Streams or pub/sub for order events that workers must not miss?",
+    "How should I name and expire keys in Valkey for per-user session data?"
+  ],
+  "should_not_trigger": [
+    "Design a MongoDB schema for orders with embedded line items",
+    "Our Postgres query on the orders table is slow, can you look at the plan?",
+    "Set up a ClickHouse table for page view events partitioned by month",
+    "Write a docker-compose file that runs our API and its database",
+    "Fix the N+1 queries in our Prisma resolvers",
+    "Deploy our cache cluster with a Kubernetes StatefulSet and Helm chart"
+  ]
+}

package/skills/redis-patterns/references/operations.md

@@ -0,0 +1,61 @@
+# Redis operations reference
+
+Read this before changing `maxmemory`, eviction or persistence settings. Confirm every setting against the server's own `redis.conf` and the redis.io docs for its version; managed services (ElastiCache, Memorystore, Azure Cache, Upstash, Redis Cloud) expose only some of these, through their own console or parameter groups.
+
+## Inspect first (read-only)
+
+```
+redis-cli INFO server        # version, mode
+redis-cli INFO memory        # used_memory, maxmemory, mem_fragmentation_ratio, mem_not_counted_for_evict
+redis-cli INFO stats         # keyspace_hits, keyspace_misses, evicted_keys, expired_keys
+redis-cli INFO persistence   # rdb_last_bgsave_status, aof_enabled, aof_last_write_status
+redis-cli CONFIG GET maxmemory*
+redis-cli CONFIG GET appendonly
+redis-cli CONFIG GET save
+redis-cli SLOWLOG GET 20
+redis-cli --bigkeys          # samples with SCAN, safe on a live server but adds load
+redis-cli --memkeys
+```
+
+Hit rate: `keyspace_hits / (keyspace_hits + keyspace_misses)`. A low hit rate with high `evicted_keys` means memory is too small or the policy is wrong. A low hit rate with high `expired_keys` means TTLs are too short.
+
+## maxmemory
+
+- `maxmemory 0` means no limit on 64-bit builds. In a container, that means the kernel kills Redis instead of Redis evicting keys.
+- Replication and AOF buffers are not counted toward `maxmemory`. Leave headroom: a common starting point is 70 to 80 percent of the memory available to the process, then adjust using `mem_not_counted_for_evict`.
+- A fork for `BGSAVE` or AOF rewrite uses copy-on-write memory; on a write-heavy instance, the peak can approach double the dataset.
+
+## maxmemory-policy
+
+| Policy | Evicts | Use for |
+|---|---|---|
+| `noeviction` (default) | nothing; writes that need memory fail with an OOM error | stores, queues, anything that must not lose keys |
+| `allkeys-lru` | least recently used, any key | general cache (good default) |
+| `allkeys-lfu` | least frequently used, any key | cache with a stable hot set |
+| `allkeys-random` | random | uniform access |
+| `volatile-lru` / `volatile-lfu` / `volatile-random` | only keys with a TTL | mixed instance (prefer two instances) |
+| `volatile-ttl` | keys with the shortest remaining TTL | app assigns short TTLs to cheap keys |
+
+Recent Redis 8 releases add `allkeys-lrm` and `volatile-lrm` (least recently modified); check the redis.io eviction docs and release notes for the server version before using them. `volatile-*` policies behave like `noeviction` when no key has a TTL.
+
+## Persistence
+
+| Setting | Meaning |
+|---|---|
+| `appendonly yes` | write every change to the AOF |
+| `appendfsync everysec` | fsync once a second: lose at most about a second on power loss (usual choice) |
+| `appendfsync always` | fsync every write: safest, slowest |
+| `appendfsync no` | let the OS decide |
+| `save <seconds> <changes>` | RDB snapshot rules; `save ""` disables snapshots |
+
+- Store: AOF `everysec` plus RDB snapshots copied off the host for backups. Test a restore.
+- Cache: persistence optional. Without it, a restart starts cold, so plan for the load on the database.
+- Check `rdb_last_bgsave_status` and `aof_last_write_status` are `ok` after any change.
+
+## Latency checklist
+
+1. `SLOWLOG GET`: look for `KEYS`, `HGETALL`/`SMEMBERS` on large keys, long Lua scripts, `DEL` on big keys.
+2. `--bigkeys`: split or page anything huge; use `UNLINK` to delete.
+3. Network: round trips dominate small commands; pipeline or use multi-key commands.
+4. Connections: one shared client or pool per process, not a new connection per request. Check `INFO clients` for `connected_clients` climbing.
+5. Fork pauses: `INFO stats` `latest_fork_usec`; large datasets fork slowly.

package/skills/refactoring-safely/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: refactoring-safely
+description: Step-by-step method for restructuring code while proving its observable behaviour stays identical, by pinning current output with characterisation tests, making one small reversible move at a time, preferring automated IDE-style transformations, and using a strangler fig to replace large legacy modules incrementally. Use when renaming, extracting, moving or splitting code, untangling a legacy module, or planning a rewrite that must not break existing users.
+license: MIT
+compatibility: Any Agent Skills host. Needs git and the project's test runner.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git"
+  kete-loom/owner: "Kete-org"
+---
+
+# Refactoring safely
+
+A refactor changes structure, never behaviour. If behaviour changes, it is a feature or a fix and goes in a separate commit.
+
+## 0. Before you start
+
+1. State the goal in one sentence ("split `OrderService` so pricing can be tested alone"). If you can't, ask the user what the refactor is for.
+2. Check the working tree is clean (`git status`). If not, **stop and ask** whether to commit or stash the user's changes first.
+3. Find and run the test command. Record the result.
+   - If tests already fail, **stop and tell the user**. Do not refactor on a red suite.
+4. Search the codebase for every user of the code you will touch: callers, imports, reflection or string lookups, config files, templates, public API docs, other repos if it is a published package.
+5. If the code is a public API (exported from a library, an HTTP endpoint, a CLI flag, a database column), **stop and ask** before changing its shape. Plan a deprecation instead.
+
+## 1. Pin current behaviour (characterisation tests)
+
+If the code you will change is not covered by tests that would fail on a behaviour change, write them first.
+
+1. Call the code through its public entry point with realistic inputs, including edge cases: empty, null, boundary values, error paths.
+2. Assert what it **does today**, even if it looks wrong. Note suspected bugs in a list for the user; do not fix them now.
+3. For output-heavy code (reports, rendering, serialisers), use snapshot or golden-file tests.
+4. Make each new test fail once on purpose (change an expected value) to prove it actually checks something, then restore it.
+5. Commit the tests alone: "test: characterise X before refactor".
+
+## 2. Plan the steps
+
+Break the refactor into steps that each:
+
+- Keep the build and tests green.
+- Are small enough to revert with one `git revert` or `git checkout`.
+- Change one thing: rename, or move, or extract. Not all three.
+
+Write the step list down before starting. If it has more than about 10 steps or crosses module boundaries, show it to the user first.
+
+## 3. Prefer mechanical refactors
+
+Use automated transformations from the language server, IDE or a codemod tool where available: rename symbol, extract function or variable, inline, move file with import updates, change signature. They are safer than hand edits because they update every reference.
+
+Common moves, safest first:
+
+| Move | Watch out for |
+|---|---|
+| Rename | String-based lookups, serialised field names, logs others parse |
+| Extract function or variable | Evaluation order, side effects, early returns |
+| Inline | Expressions with side effects evaluated more or fewer times |
+| Move to another module | Circular imports, init order, package visibility |
+| Change signature | Default arguments, callers in other packages, mocks in tests |
+| Replace conditional with polymorphism | Missing cases; add a test per branch first |
+
+For hand edits, search for every reference before and after, and compare counts.
+
+## 4. The loop
+
+For each step:
+
+1. Make the single change.
+2. Run the build or type-check, then the tests for the affected area.
+3. Green: commit with a message like "refactor: extract computeTax from Invoice". Red: **revert the step**, don't debug forward. Then take a smaller step.
+4. Every few steps, run the full suite.
+
+## 5. Large rewrites: strangler fig
+
+When a module is too large to refactor in place:
+
+1. Put a seam in front of it: an interface, a facade, a router or a proxy that all callers go through. Ship that alone, with no behaviour change.
+2. Build the new implementation behind the same seam, one capability at a time.
+3. Route a slice of traffic or one use case to the new code (feature flag, config switch, path-based routing).
+4. Compare: run old and new side by side on the same inputs where you can (shadow traffic, dual-run tests) and diff the results.
+5. When a capability matches, move all callers to it and delete the old path for that capability.
+6. Repeat until the old module has no callers, then delete it.
+
+Never run a big-bang rewrite that replaces everything in one release. If the user asks for one, explain the risk and offer the strangler plan.
+
+## 6. Rules
+
+- Never change behaviour and structure in the same commit.
+- Never delete, skip or loosen a test to make a refactor pass. A failing test means behaviour changed.
+- Never reformat whole files in a refactor commit; it hides the real diff. Do formatting in its own commit.
+- Do not refactor code unrelated to the stated goal, however tempting.
+- Keep performance-sensitive code paths' complexity the same unless the user agreed to change it.
+
+## 7. Finish
+
+1. Run the full test suite, linter and type-check.
+2. Diff the start and end of the branch and check that the public API is unchanged (exports, endpoints, signatures), unless agreed.
+3. Report:
+
+```
+Refactor: <goal>
+Steps: <n> commits, each green
+Characterisation tests added: <files> | none needed (existing coverage: <files>)
+Public API changed: no | yes, agreed: <what>
+Suspected bugs found, not fixed: <list> | none
+Checks: <commands run> -> <pass/fail>
+```

package/skills/refactoring-safely/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Split this 2000-line OrderService into smaller classes without breaking anything",
+    "I want to rename the User model's fields across the codebase safely",
+    "Plan how to replace our legacy billing module gradually instead of a big-bang rewrite",
+    "Add characterisation tests to this untested parser before I restructure it",
+    "Extract the pricing logic out of the controller and move it into its own module"
+  ],
+  "should_not_trigger": [
+    "Find and delete dead code and unused exports in this repo",
+    "Simplify the function I just wrote, it has too much nesting",
+    "Write a failing test first, then implement the discount feature",
+    "Fix the build error after upgrading the Go version",
+    "Review my pull request for correctness bugs",
+    "Should we adopt hexagonal architecture for the new service?"
+  ]
+}