@ericrisco/rsc 0.1.44 → 0.1.46

package/skills/react/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: react
-description: "Use when building or reviewing a client-side React SPA on Vite (React 19.2 — components, where state lives, hooks, client routing, server data fetching) and NOT server-rendered React. Triggers: 'React + Vite app', 'I'm fetching in useEffect and it fires twice', 'where should this filter state live', 'my list flickers and the wrong row updates', 'set up React Router', 'cómo hago data fetching en React sin useEffect', 'per què es re-renderitza tot l'arbre'. NOT App Router / server components / SSR (that is nextjs); NOT mobile screens (that is react-native)."
+description: "Use when building or reviewing a client-side React SPA bundled by Vite (React 19.2): components, where state lives, hooks, server data fetching, client routing, re-render and effect bugs. NOT App Router / server components / SSR (that is `nextjs`); NOT native screens (that is `react-native`)."
 tags: [react, vite, spa, frontend, hooks, tanstack-query]
 recommends: [typescript, design, testing-web]
 origin: risco
@@ -10,42 +10,23 @@ origin: risco
 
 > Build or review a fast, typed, correctly-architected **client-side** React single-page app bundled by Vite. No server runtime, no RSC tree, no framework router. Server-rendered React (App Router, server actions, SSR/SSG) is not this skill — that is `../nextjs/SKILL.md`.
 
-## When to use
-
-> **⚠️ SDD new-feature gate — read this first.** If this skill fired on a **new, non-trivial feature or behaviour change** and there is **no approved spec + plan** under `02-DOCS/wiki/sdd/`, STOP — do **not** write feature code yet. Hand off to `../specify/SKILL.md` first: it runs brainstorm → spec → plan → tasks before any code, then routes back here once the plan is approved. Build here directly only for a genuinely one-line / low-risk change. Method: `../sdd/SKILL.md`.
-
-- A repo with `vite.config.{ts,js}` + `react` + `react-dom` and **no** `next` and **no** `@react-router/dev` framework mode — i.e. an SPA.
-- Creating components and deciding **where state lives** (local / lifted / URL / context / store).
-- Wiring **server data**: queries, mutations, caching, optimistic UI.
-- Client routing (React Router v7 *library mode* or TanStack Router).
-- Fixing re-render storms, stale closures, effect misuse, `key` bugs.
-- Setting up the Vite project (aliases, env vars, code-splitting, `dist/` build).
-
-## When NOT to use — route it
-
-- Server Components, server actions, App Router, SSR/SSG, `app/` dir → `../nextjs/SKILL.md`.
-- React Native / Expo / native screens → `../react-native/SKILL.md`.
-- The type system itself (generics, discriminated unions, `tsconfig` theory) with no React shape → `../typescript/SKILL.md`.
-- Visual design, tokens, spacing, button states → `../design/SKILL.md`.
-- Writing the Vitest/RTL or E2E suite as the task → `../testing-web/SKILL.md`.
-- Hosting the built `dist/` → `../deployment/SKILL.md`.
+**SDD gate — before writing feature code.** If this skill fired on a **new, non-trivial feature or behaviour change** and there is **no approved spec + plan** under `02-DOCS/wiki/sdd/`, stop and hand off to `../specify/SKILL.md`: it runs brainstorm → spec → plan → tasks, then routes back here once the plan is approved. Build directly only for a genuinely one-line / low-risk change. Method: `../sdd/SKILL.md`.
 
 ## First: confirm it's a Vite SPA, not a framework
 
-Do this before giving any advice — it stops you applying SSR/RSC patterns to a client SPA.
-
-1. Read `package.json`. `vite` + `react` present? Good.
-2. Is `next` present? → stop, use `../nextjs/SKILL.md`.
-3. Is `@react-router/dev` present (React Router **framework mode** = SSR, Remix successor)? → that is out of scope, closer to nextjs-shape. Library mode (`react-router` / `react-router-dom` alone) stays here.
-4. Pick the data layer (**TanStack Query**, always — see §6) and the router (React Router v7 library mode *or* TanStack Router).
+Read `package.json` before giving any advice — it stops you applying SSR/RSC patterns to a client SPA.
 
 | Signal in package.json                | Read it as            | Where                  |
 | ------------------------------------- | --------------------- | ---------------------- |
 | `vite` + `react`, no `next`           | Vite SPA              | here                   |
 | `next`                                | metaframework / RSC   | `../nextjs/SKILL.md`   |
-| `@react-router/dev`                   | RR framework mode/SSR | `../nextjs/SKILL.md`-shape |
-| `react-router` only                   | RR library mode       | here (§7)              |
-| `expo` / `react-native`               | native               | `../react-native/SKILL.md` |
+| `@react-router/dev`                   | RR framework mode/SSR (Remix successor) | `../nextjs/SKILL.md`-shape |
+| `react-router` only                   | RR library mode       | here (Routing)         |
+| `expo` / `react-native`               | native                | `../react-native/SKILL.md` |
+
+Then pick the data layer (**TanStack Query**, always) and the router (React Router v7 library mode *or* TanStack Router).
+
+Adjacent jobs route out: the type system itself (generics, discriminated unions, `tsconfig` theory) with no React shape → `../typescript/SKILL.md`; visual design, tokens, spacing, button states → `../design/SKILL.md`; writing the Vitest/RTL or E2E suite as the task → `../testing-web/SKILL.md`; hosting the built `dist/` → `../deployment/SKILL.md`.
 
 ## Component & state architecture
 
@@ -62,7 +43,7 @@ Do this before giving any advice — it stops you applying SSR/RSC patterns to a
 | URL search params                       | it should be shareable / bookmarkable / survive reload         |
 | Context                                 | wide read, **low** write frequency (theme, auth user)          |
 | External store (Zustand) + selectors    | wide read, **high** write frequency, or deep prop-drilling     |
-| TanStack Query cache                    | it's **server** data (anything fetched) — see §6               |
+| TanStack Query cache                    | it's **server** data (anything fetched)                        |
 
 ```tsx
 // Bad: syncing a derived value into state with an effect → stale + extra render
@@ -76,7 +57,7 @@ const fullName = `${first} ${last}`;
 ## Hooks discipline (React 19.2)
 
 - `useState` for one or two independent values; `useReducer` when the next state depends on the previous one or several fields move together.
-- **The `useEffect` rule:** effects exist to *synchronize with a non-React external system* (a subscription, a DOM node, a non-React widget). They are **not** for transforming data and **not** for fetching server data (§6). If you can compute it in render or in an event handler, do that instead.
+- **The `useEffect` rule:** effects exist to *synchronize with a non-React external system* (a subscription, a DOM node, a non-React widget). They are **not** for transforming data and **not** for fetching server data. If you can compute it in render or in an event handler, do that instead.
 - **`useEffectEvent`** (stable in 19.2): extract the non-reactive part of an effect so it reads the latest props/state without being a dependency. Fixes the stale-closure / over-firing class of effect bug.
 
 ```tsx
@@ -96,7 +77,7 @@ useEffect(() => {
 function Profile({ id }: { id: string }) {
   const user = use(fetch(`/api/users/${id}`).then(r => r.json())); // ❌
 }
-// Good: the promise is owned by a cache (see §6 useSuspenseQuery)
+// Good: the promise is owned by a cache (useSuspenseQuery, below)
 ```
 
 - **`useTransition` / `useDeferredValue`** keep the UI responsive: mark a slow state update non-urgent so typing/clicks stay live.
@@ -132,7 +113,8 @@ const remove = useMutation({
 ```
 
 - **`useSuspenseQuery`** + `<Suspense fallback>` + an error boundary moves loading/error out of the component body and is the correct source for `use()`-style reads.
-- **Optimistic delete**: `onMutate` snapshots + writes the expected state, `onError` rolls back, `onSettled` invalidates. Full pattern (infinite, prefetch, query-key factory, optimistic) → `references/data-and-state.md`.
+- **Optimistic delete**: `onMutate` snapshots + writes the expected state, `onError` rolls back, `onSettled` invalidates.
+- Query-key factory, `invalidateQueries` vs `setQueryData`, infinite queries, prefetch, Zustand store + selectors, the full Bad→Good set → `references/data-and-state.md`.
 
 ## Routing (client-side)
 
@@ -151,7 +133,7 @@ const router = createBrowserRouter([
 - Use **lazy routes** so each route is its own chunk.
 - **TanStack Router** is the type-safe alternative — fully typed params/search, first-class loaders. Pick it when route/search typing matters.
 - `@react-router/dev` **framework mode** is SSR → treat like nextjs, out of scope.
-- Protected routes, `useSearchParams`-as-state, nested loaders → `references/routing.md`.
+- Nested/lazy routes, client loaders, protected-route wrapper, `useSearchParams`-as-state → `references/routing.md`.
 
 ## Performance
 
@@ -162,7 +144,7 @@ const router = createBrowserRouter([
 - **Code-split** routes and heavy components with `lazy()` + `<Suspense>`; Vite splits automatically on dynamic `import()`.
 - **React Compiler on** ⇒ delete manual `useMemo`/`useCallback`/`React.memo` — it auto-memoizes; leaving them in is dead noise.
 - **Narrow store selectors** so a slice change doesn't re-render the whole subtree.
-- Targets: LCP < 2.5s, INP < 200ms, CLS < 0.1. Deep dive → `references/performance.md`.
+- Targets: LCP < 2.5s, INP < 200ms, CLS < 0.1. Profiler workflow, React Compiler Vite setup, bundle analysis, re-render map → `references/performance.md`.
 
 ## TypeScript + Vite project setup
 
@@ -174,7 +156,7 @@ const router = createBrowserRouter([
 
 ## Anti-patterns → STOP
 
-| Rationalization                                       | Reality                                                                 | Do instead                                          |
+| Anti-pattern                                          | Reality                                                                 | Do instead                                          |
 | ----------------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------- |
 | "Fetch in `useEffect`, it's simpler"                  | Waterfalls, races, double-fire, no cache/dedupe                          | `useQuery` / `useSuspenseQuery`                     |
 | "Create the promise inline for `use()`"               | New promise every render → suspends forever                              | Promise owned by a cache (TanStack Query)           |
@@ -185,40 +167,10 @@ const router = createBrowserRouter([
 | "`VITE_API_SECRET` is fine, it's an env var"          | It ships in the browser bundle — fully public                            | Proxy the secret through a backend                  |
 | "`useEffect` to compute a derived value"              | Extra render + a stale window                                            | Recompute in render                                 |
 
-## Quick reference
-
-| Task                                | API / tool                                  | Note                                  |
-| ----------------------------------- | ------------------------------------------- | ------------------------------------- |
-| Server data                         | `useQuery`                                  | `queryKey` + `queryFn` + `staleTime`  |
-| Mutation                            | `useMutation` + `invalidateQueries`         | or optimistic `onMutate/onError/onSettled` |
-| Read a promise in render            | `use()` + `<Suspense>` + error boundary     | promise from a cache, never inline    |
-| High-frequency global state         | Zustand + selector                          | narrow the selector                   |
-| Wide, low-write state               | `<Context value>`                           | theme/auth, not server data           |
-| Keep UI responsive                  | `useTransition` / `useDeferredValue`        | mark slow update non-urgent           |
-| Non-reactive logic inside an effect | `useEffectEvent`                            | reads latest, not a dependency        |
-| Client route                        | `createBrowserRouter` + `RouterProvider`    | lazy routes for splitting             |
-| Code-split                          | `lazy()` + `<Suspense>`                      | Vite splits on dynamic `import()`     |
-| Build                               | `vite build`                                | emits `dist/`                         |
-
 ## Verify
 
-`scripts/verify.sh` runs from the project root: **ESLint → `tsc --noEmit` → Vitest → `vite build`**, in that order. Each tool is detected and **skipped with a warning (never a failure) if absent** — a repo without a tool can't fail a command it doesn't have. The final `vite build` writes `dist/`; the lint/type/test steps are read-only. No installs, no network mutations, safe to re-run. It exits non-zero only on a real tool failure, and exits 0 on a clean/empty target.
-
-## References
-
-- `references/data-and-state.md` — TanStack Query v5 in depth (query-key factory, mutations, `invalidateQueries` vs `setQueryData`, optimistic with `onMutate/onError/onSettled`, `useSuspenseQuery`, infinite, prefetch), Zustand store + selectors, context patterns, full Bad→Good set.
-- `references/routing.md` — React Router v7 library mode (nested/lazy routes, client loaders, protected-route wrapper, `useSearchParams` as state) and the TanStack Router type-safe alternative; framework mode → defer.
-- `references/performance.md` — Profiler workflow, `key` bugs, `react-virtual`, code-splitting, React Compiler Vite setup, bundle analysis, narrow-selector re-render map.
+`scripts/verify.sh` runs from the project root: **ESLint → `tsc --noEmit` → Vitest → `vite build`**, in that order. Each tool is detected and **skipped with a warning (never a failure) if absent**. The final `vite build` writes `dist/`; the lint/type/test steps are read-only. No installs, no network mutations, safe to re-run. It exits non-zero only on a real tool failure, and exits 0 on a clean/empty target.
 
 ## Project grounding (02-DOCS)
 
 If the workspace has `02-DOCS/`, record stack-specific React conventions (chosen router, store, query defaults) in `02-DOCS/wiki/stack/react.md` and index it from `CLAUDE.md`. Recorded, not gated — skip silently if there is no `02-DOCS/`.
-
-## See also
-
-- `../nextjs/SKILL.md` — the SSR / RSC / App Router sibling (server-rendered React).
-- `../react-native/SKILL.md` — native mobile React.
-- `../typescript/SKILL.md` — the type system itself.
-- `../design/SKILL.md` — visual design, tokens, component states.
-- `../testing-web/SKILL.md` — Vitest/RTL test authoring.
-- `../deployment/SKILL.md` — hosting the built `dist/`.

package/skills/review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review
-description: "Use when giving OR receiving an adversarial code review in the rsc SDD chain — after implement/verify and before ship. Triggers: 'review this PR', 'review my diff', 'revisa este código', 'critique this change', 'be my reviewer', 'tear this apart', 'what's wrong with this code', plus the receiving side: 'the reviewer said X', 'address this review comment', 'they want me to change Y', 'do I have to do what the review says', 'PR feedback', 'someone left comments on my PR'. Covers the full loop: producing a rigorous, evidence-backed review keyed to the spec/plan/constitution under 02-DOCS/wiki/sdd/, AND processing incoming feedback with technical rigor — verify each finding against the code before agreeing, push back on the wrong ones, fix the real ones. NOT running lint/type/test gates (that's the verify phase) and NOT merging/closing the branch (that's ship). No performative agreement; points to ship when the diff survives review."
+description: "Use when a green diff needs adversarial judgment in the rsc SDD chain, between verify and ship — give a review keyed to the spec/plan/constitution in 02-DOCS/wiki/sdd/, or receive one and verify each comment before agreeing. NOT running lint/type/tests (that is `verify`), NOT the spec-less standalone pass (that is `code-review`), NOT merging (that is `ship`)."
 tags: [sdd, review, code-review]
 recommends: [ship]
 profiles: [core, full]
@@ -16,37 +16,18 @@ This skill owns **two roles that share one discipline**:
 - **Giving** a review — read a diff adversarially, find the real defects, rank them by impact, ship the verdict as evidence not opinion.
 - **Receiving** a review — take incoming feedback (human or machine), verify each point against the code *before* acting, fix the real findings, and push back — with proof — on the wrong ones.
 
-The discipline is the same in both directions: **claims are backed by evidence, never by deference.** A reviewer who waves through a bug to be agreeable, and an author who edits working code because a comment *sounded* authoritative, are making the same mistake. This skill exists to kill both.
+The discipline is the same in both directions: **every finding and every rebuttal carries evidence — no agreement without verification, no objection without a defect.** A reviewer who waves through a bug to be agreeable, and an author who edits working code because a comment *sounded* authoritative, are making the same mistake. Everything below is in service of that one rule.
+
+**Route out** when the ask isn't this gate: a deep OWASP / threat-model pass belongs to `../secure-coding/SKILL.md` (review folds its findings in, but the dedicated pass is owned there); a "is this idiomatic React/FastAPI/Go/SQL" question belongs to the stack skill (`../nextjs/SKILL.md`, `../fastapi/SKILL.md`, `../go/SKILL.md`, `../postgresdb/SKILL.md`, `../flutter/SKILL.md`) — pull the idiom there, then judge against it here.
 
 ## Read these first
 
-1. `02-DOCS/wiki/harness/user-profile.md` — the **accompaniment dial** (L0..L3). It sets how much you narrate, not how rigorous you are. Rigor is fixed; verbosity is dialled. See "Accompaniment dial" below.
-2. `02-DOCS/wiki/sdd/specs/<slug>.md` and `02-DOCS/wiki/sdd/plans/<slug>.md` — what the diff was *supposed* to do. A review with no spec is a review of vibes.
-3. `02-DOCS/wiki/sdd/constitution.md` — the project's non-negotiables (stack canon, quality bars, conventions). Constitution violations are findings even when the code "works".
+1. `02-DOCS/wiki/sdd/specs/<slug>.md` and `02-DOCS/wiki/sdd/plans/<slug>.md` — what the diff was *supposed* to do. A review with no spec is a review of vibes.
+2. `02-DOCS/wiki/sdd/constitution.md` — the project's non-negotiables (stack canon, quality bars, conventions). Constitution violations are findings even when the code "works".
+3. `02-DOCS/wiki/harness/user-profile.md` — the accompaniment dial (see "Narration dial" below).
 
 If there is no spec/plan (someone jumped straight to code), say so and review against the constitution + the diff's own stated intent. Don't pretend a spec exists.
 
-## When to use / When NOT to use
-
-Use when:
-
-- A diff, branch, or PR is ready and you want it torn apart before it ships.
-- You are the author and a review landed — comments from a teammate, a bot, or another agent — and you need to decide what to actually change.
-- A "review comment" feels wrong, vague, or technically questionable and you're tempted to just comply.
-
-Do NOT use when (route elsewhere):
-
-- You need lint / type-check / test / audit to run and go green → that's the **verify** phase, run before review.
-- The diff has survived review and you want to PR / merge / close the branch → that's the **ship** phase (and ship enforces Eric-only git authorship).
-- It's specifically a *security* threat-model / OWASP pass → `../secure-coding/SKILL.md` (review folds in its findings, but the deep pass is owned there).
-- The "review" is really framework-level "is this idiomatic React/FastAPI/Go" — pull the relevant stack skill (`../nextjs/SKILL.md`, `../fastapi/SKILL.md`, `../go/SKILL.md`, `../postgresdb/SKILL.md`, `../flutter/SKILL.md`) for the idiom, then judge against it here.
-
-## The one rule
-
-> **Every finding and every rebuttal carries evidence. No agreement without verification, no objection without a defect.**
-
-Everything below is in service of that rule.
-
 ## Confidence filtering
 
 A review's value is its signal-to-noise. Every finding you report costs the author triage time, so report only what you can stand behind:
@@ -56,14 +37,7 @@ A review's value is its signal-to-noise. Every finding you report costs the auth
 - **Common false positives to skip:** patterns guarded two functions up; "unsafe" calls on values that are provably constant/internal; missing checks the framework already enforces; style the linter owns; defects behind a flag that's off everywhere (note as `nit`, not blocker); test-only or generated code held to prod standards.
 - **No severity inflation.** A `should-fix` dressed as a `blocker` burns the same trust as a missed bug. Rank by actual blast radius and reachability — if everything is a blocker, nothing is.
 
-## Executable review
-
-This skill is the **discipline**; the **`rsc-review` bundle is its automated counterpart**. When you want the doctrine above run for you over a real diff:
-
-- **`/code-review [pr]`** — fans the diff out to the per-language reviewer fleet (`code-reviewer`, `web-reviewer`, `python-reviewer`, `go-reviewer`, `sql-reviewer`, `flutter-reviewer`) in parallel and aggregates one ranked verdict.
-- **`/security-scan`** — two-layer security pass: automated scanners plus the `security-reviewer` agent, merged into one exploitability-ranked report.
-
-Those commands and agents enforce the same evidence bar and the same confidence filtering described here — they are this skill, executed.
+This skill is the discipline; the **`rsc-review` bundle is it executed** — `/code-review [pr]` fans a diff out to the per-language reviewer fleet and aggregates one ranked verdict, `/security-scan` merges automated scanners with the `security-reviewer` agent into an exploitability-ranked report. Both enforce the same evidence bar and confidence filtering described here.
 
 ---
 
@@ -114,14 +88,12 @@ A finding without a `repro` or a mechanism is a *suspicion*. Label it `[question
 
 ### Verify before you flag
 
-The reviewer is held to the same evidence bar as the author. Before writing a `blocker`:
+The reviewer is held to the same evidence bar as the author, because a reviewer who cries blocker on a non-bug burns the same trust as an author who ships one. Before writing a `blocker`:
 
 - **Read the surrounding code**, not just the diff hunk. The check you think is missing may live two functions up.
 - **Trace the value**, don't pattern-match. "This looks like SQL injection" is not a finding; "this f-string interpolates `request.args['q']` straight into `execute()`" is.
 - **Confirm the path is reachable.** A defect behind a flag that's off in every environment is a `nit`, not a `blocker` — say so.
 
-A reviewer who cries blocker on a non-bug burns the same trust as an author who ships one.
-
 ### The verdict
 
 End every review you give with one of three, and nothing mushy in between:
@@ -184,21 +156,6 @@ When you've processed the review, summarize for the reviewer (and the decisions
 
 ---
 
-## Model tier — `heavy` (opt-in routing)
-
-This phase's default model tier is **`heavy`** — adversarial diff reading is where the strongest model pays off most. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch per the accompaniment dial when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
-
-## Accompaniment dial (L0..L3)
-
-Read the level from `02-DOCS/wiki/harness/user-profile.md`. **It changes the narration, never the rigor** — every level runs the same passes and the same evidence bar.
-
-- **L0** — verdict + the blocker list, terse. `CHANGES REQUESTED: 1 blocker (auth, documents.py:42), 1 nit. Fix the auth scope and re-run verify.`
-- **L1** — each finding gets its one-line *why*.
-- **L2** — full finding format (where/why/repro/fix); explain why each blocker blocks.
-- **L3** — the above plus teaching: name the defect class (IDOR, N+1, TOCTOU), why the boundary matters, and how to not reintroduce it. For non-technical authors, translate the impact ("any logged-in person could read everyone else's documents").
-
-When no profile exists, default to L2 and proceed — don't stall a review to ask for a dial setting.
-
 ## Anti-patterns → STOP
 
 | Rationalization | Reality |
@@ -212,6 +169,19 @@ When no profile exists, default to L2 and proceed — don't stall a review to as
 | "I'll approve it, the issues are minor" | If they're truly minor, label them nits and approve. If they block, don't approve. No mushy middle. |
 | "No spec, so I'll just eyeball it" | Say there's no spec and review against the constitution + stated intent. Don't fake a baseline. |
 
+## Narration dial
+
+Read the level from `02-DOCS/wiki/harness/user-profile.md`. It changes what a review *shows*, never its rigor — every level runs the same passes and the same evidence bar. No profile → default L2 and proceed; don't stall a review to ask for a dial setting.
+
+- **L0** — verdict + the blocker list, terse. `CHANGES REQUESTED: 1 blocker (auth, documents.py:42), 1 nit. Fix the auth scope and re-run verify.`
+- **L1** — each finding gets its one-line *why*.
+- **L2** — full finding format (where/why/repro/fix); explain why each blocker blocks.
+- **L3** — the above plus teaching: name the defect class (IDOR, N+1, TOCTOU), why the boundary matters, and how to not reintroduce it. For non-technical authors, translate the impact ("any logged-in person could read everyone else's documents").
+
+## Model tier — `heavy` (opt-in routing)
+
+This phase's default model tier is **`heavy`** — adversarial diff reading is where the strongest model pays off most. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch per the narration dial when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
+
 ## Where this writes
 
 Review is mostly a conversation, but two artifacts persist into the harness wiki so the knowledge model grows:

package/skills/rust/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rust
-description: "Use when writing, reviewing, testing, or shipping Rust code or async services - ownership/borrowing (move vs borrow vs clone, Arc/Rc/RefCell, lifetimes), error modeling with Result/?/thiserror/anyhow, async on tokio (.await, JoinSet, select!, spawn_blocking, Send-across-await), axum 0.8 HTTP handlers/extractors/State, cargo test (unit/integration/doctests), and sqlx + cargo-audit security. Triggers: \"write an axum/tokio service\", \"is this idiomatic Rust\", \"add tests\", compiler error text like \"value moved here\", \"borrow of moved value\", \"future cannot be sent between threads safely\", \"does not live long enough\", \"cannot borrow as mutable\", \"el borrow checker no em deixa\", \"petición async en Rust\", .rs files, Cargo.toml, thiserror, sqlx. NOT desktop/GUI shells (that is tauri)."
+description: "Use when writing, reviewing, testing, or shipping Rust — ownership and the borrow checker (move/borrow/clone, Arc/RefCell, lifetimes), errors with Result/`?`/thiserror/anyhow, async on tokio, axum 0.8 services, cargo test, and sqlx + cargo-audit hardening. NOT the same service in Go (that is `go`), NOT a desktop webview shell (that is `tauri`)."
 tags: [rust, tokio, axum, async, backend, service]
 recommends: [go, postgresdb, secure-coding, deployment]
 origin: risco
@@ -21,60 +21,12 @@ The thing an agent gets wrong in Rust is almost never syntax — it is *ownershi
 compile errors about moves, borrows, and `Send + Sync` across `.await`. Front-load that mental model;
 the rest follows.
 
-## When to use / When NOT to use
-
-**Use when:**
-
-- Authoring, reviewing, or testing any `.rs` file, `Cargo.toml`, or workspace.
-- Fighting the borrow checker: "value moved here", "cannot borrow as mutable", "does not live long
-  enough", or choosing between `Rc`/`Arc`/`RefCell`/`Mutex`.
-- Modeling errors: `Result<T, E>`, `?`, a `thiserror` enum vs `anyhow::Result`, `#[from]` conversions,
-  mapping a domain error to an HTTP status.
-- Async on tokio: `#[tokio::main]`, `.await`, `JoinSet`, `select!`, channels, `spawn_blocking`,
-  cancellation, the "future is not `Send`" / "held across await" error class.
-- Building an axum service: routers, extractors, `State`, `IntoResponse`, tower middleware, shutdown.
-
-**When NOT to use (delegate):**
-
-- Language-agnostic threat modeling / authz / OWASP review -> `secure-coding` (this skill keeps the
-  Rust-specific controls: sqlx parametrization, `#![forbid(unsafe_code)]`, `cargo audit`).
-- Dockerfile / CI pipeline / shipping infra -> `deployment` (this skill carries only a multi-stage
-  Docker note + release-profile flags).
-- Pure SQL schema/index tuning -> `postgresdb` (this skill covers only the Rust-side sqlx query).
-- Native GUI / desktop shell with a webview -> `tauri`; cross-platform app work is out of scope.
-- A Go / Python / Node service -> `go` / `fastapi` / `nodejs` respectively.
-
-Rust error modeling and the HTTP error->status contract live **here**, in Rust terms — they are not a
-separate skill. `go` is the structural twin: same shape, GC + goroutines instead of ownership + futures.
-
-## Decision rules
-
-Apply these on every Rust edit:
-
-1. Prefer borrowing (`&T`) over moving over cloning; `.clone()` to silence the borrow checker is a
-   smell, not a fix — it hides the real ownership question.
-2. Take `&str`/`&[T]` in function params, return owned `String`/`Vec<T>`; borrow on the way in, own on
-   the way out. It is the most flexible and the cheapest.
-3. `?` over `.unwrap()`/`.expect()` everywhere off the test path; an `.unwrap()` on untrusted input is a
-   remote panic.
-4. Model errors with a `thiserror` enum when callers branch on the failure mode; reach for `anyhow` only
-   at the application boundary (`main`, top-level handlers) where you just need context + a backtrace.
-5. Never hold a `MutexGuard` (or any non-`Send` value) across an `.await` — it deadlocks or fails to
-   compile with "future cannot be sent between threads".
-6. Bound concurrency with a `JoinSet` (or a semaphore); a loop of bare `tokio::spawn` is unbounded
-   fan-out that can exhaust the runtime.
-7. `spawn_blocking` for CPU-bound or synchronous-blocking work; blocking inside an async task starves
-   the executor's worker threads.
-8. Validate at the boundary, parse into a typed domain model; "parse, don't validate" — make illegal
-   states unrepresentable.
-9. Parametrize every sqlx query with bind args; `format!` into SQL is injection.
-10. `#![forbid(unsafe_code)]` at the crate root unless you have a measured, reviewed, documented reason;
-    `clippy -D warnings` and `cargo fmt --check` are build gates, not suggestions.
-
 ## Ownership & borrowing (essentials)
 
 This is the skill's center of gravity. Three moves: **move** (transfer ownership), **borrow** (`&`/`&mut`,
-no transfer), **clone** (a real copy, real cost).
+no transfer), **clone** (a real copy, real cost) — and prefer them in that order, borrow first.
+Take `&str`/`&[T]` in function params, return owned `String`/`Vec<T>`: borrow on the way in, own on the
+way out is both the most flexible and the cheapest.
 
 ```rust
 fn print_name(name: &str) { println!("{name}"); }   // borrows; caller keeps ownership
@@ -127,8 +79,8 @@ Lifetimes, `'static`, `Cow`, and the full smart-pointer tree -> `references/owne
 
 ## Errors
 
-Error modeling is owned here. The model: `Result<T, E>` + `?`, typed enums for libraries, `anyhow` at
-the edge, one mapping from a domain enum to an HTTP status.
+Error modeling is owned here, in Rust terms — it is not a separate skill. The model: `Result<T, E>` +
+`?`, typed enums for libraries, `anyhow` at the edge, one mapping from a domain enum to an HTTP status.
 
 ```rust
 use thiserror::Error;
@@ -172,9 +124,7 @@ impl IntoResponse for UserError {
 }
 ```
 
-**Anti-patterns:** `.unwrap()`/`.expect()` on the request path (a panic = 500 + a stack trace, or a
-crashed worker); stringly-typed errors you `match` on by message; `Box<dyn Error>` smeared everywhere so
-nothing can branch on the failure. Full repo->service->handler skeleton -> `references/axum-service.md`.
+Full repo->service->handler skeleton -> `references/axum-service.md`.
 
 ## Async (tokio, essentials)
 
@@ -242,7 +192,9 @@ let app = Router::new()
     .with_state(state);
 ```
 
-Full skeleton — tower middleware (`TraceLayer`, timeout, request-id), graceful shutdown via
+Validate at the boundary and parse into a typed domain model — "parse, don't validate" makes illegal
+states unrepresentable, so the handler body never re-checks. Full skeleton — tower middleware
+(`TraceLayer`, timeout, request-id), graceful shutdown via
 `axum::serve(...).with_graceful_shutdown(...)`, and JSON helpers -> `references/axum-service.md`.
 
 ## Project layout
@@ -302,7 +254,8 @@ sqlx::query_as!(User, "SELECT id, name FROM users WHERE id = $1", id).fetch_one(
 `#![forbid(unsafe_code)]` at the crate root; run `cargo audit` (RustSec advisories) and `cargo deny` (license
 + ban + advisory policy) in CI; never `.unwrap()` on untrusted input — a malicious request becomes a
 panic. Read secrets from env or a secret manager, never hardcode or log them. Deeper authz / threat
-modeling -> `secure-coding`.
+modeling -> [`secure-coding`](../secure-coding/SKILL.md). Pure SQL schema/index/plan tuning ->
+[`postgresdb`](../postgresdb/SKILL.md); this skill covers only the Rust-side sqlx query.
 
 ## Production
 
@@ -323,73 +276,45 @@ strip = true            # strip symbols
 
 Expose `/healthz` (static 200 liveness) and `/readyz` (pings the DB pool, 503 on failure). Docker:
 multi-stage build, `cargo build --release`, copy the binary onto a distroless/slim base. Full
-Containerfile + CI -> `deployment`.
+Containerfile + CI -> [`deployment`](../deployment/SKILL.md).
 
-## Anti-patterns / rationalizations -> STOP
+## Anti-patterns
 
-| Rationalization | Reality / Do instead |
+| Anti-pattern | Reality / Do instead |
 | --- | --- |
-| ".clone() to make the borrow checker happy" | It hides the real ownership question; borrow, or restructure who owns what. |
-| ".unwrap() here, it can't fail" | It can, and a panic on the request path is a 500/crash; use `?` + a typed error. |
-| "`Box<dyn Error>` everywhere is simpler" | Nothing can branch on the failure; use a `thiserror` enum the caller can match. |
-| "`#[async_trait]` on every async trait" | Edition 2024 has native async fn in traits; drop the macro for most cases. |
-| "lock the Mutex, then .await" | Guard held across await = deadlock / not-`Send`; drop it first or use `tokio::sync::Mutex`. |
-| "`block_on` inside this async fn" | Nesting a runtime panics/deadlocks; restructure to `.await`. |
-| "just `tokio::spawn` in the loop" | Unbounded fan-out exhausts the runtime; bound it with `JoinSet`/semaphore. |
-| "`unsafe` to get past the borrow checker" | `unsafe` turns a compile error into UB; the checker was right — restructure. |
-| "`format!` the id into the SQL, it's trusted" | Injection; bind parameters with `$1` always. |
-| "skip clippy, it's just style" | clippy catches correctness (`.unwrap()` on `Option`, await-holds-lock); gate on `-D warnings`. |
-| "`Arc<Mutex<T>>` for everything shared" | If data flows one way it is a channel; reach for `mpsc` first. |
-| "`String` params everywhere" | Take `&str`; you force needless allocations and lose flexibility. |
-
-## Quick reference
-
-| Task | Command / idiom |
+| `.clone()` to make the borrow checker happy | It hides the real ownership question; borrow, or restructure who owns what. |
+| `.unwrap()` / `.expect()` off the test path | A panic on the request path is a 500 or a crashed worker; use `?` + a typed error. |
+| Matching an error by its message string | Messages are prose and they change; match the enum variant. |
+| `Box<dyn Error>` everywhere because it is simpler | Nothing can branch on the failure; use a `thiserror` enum the caller can match. |
+| `#[async_trait]` on every async trait | Edition 2024 has native async fn in traits; drop the macro for most cases. |
+| `block_on` inside an async fn | Nesting a runtime panics or deadlocks; restructure to `.await`. |
+| A bare `tokio::spawn` per loop iteration | Unbounded fan-out exhausts the runtime; bound it with `JoinSet`/semaphore. |
+| `Arc<Mutex<T>>` for everything shared | If data flows one way it is a channel; reach for `mpsc` first. |
+| `unsafe` to get past the borrow checker | `unsafe` turns a compile error into UB; the checker was right — restructure. |
+| Skipping clippy as "just style" | clippy catches correctness (`.unwrap()` on `Option`, await-holds-lock); gate on `-D warnings`. |
+
+## Gates & commands
+
+| Task | Command |
 | --- | --- |
 | Format check | `cargo fmt --all -- --check` |
 | Lint (gate) | `cargo clippy --all-targets -- -D warnings` |
 | Test | `cargo test` / `cargo nextest run` |
 | Doctests | `cargo test --doc` |
 | Audit deps | `cargo audit` / `cargo deny check` |
-| Propagate error | `let v = thing()?;` |
-| Library error | `#[derive(Error)]` enum + `#[from]` |
-| App error | `anyhow::Result<T>` + `.context(...)` |
-| Async test | `#[tokio::test] async fn ...` |
-| Bound concurrency | `JoinSet` + `join_next().await` |
-| Off-runtime work | `spawn_blocking(move || ...).await?` |
 | Local gate | `./scripts/verify.sh` (run in your crate root) |
 
-## Project grounding (02-DOCS + CLAUDE.md)
-
-When this skill runs in a project with a `02-DOCS/` layer (the
-[`harness`](../harness/SKILL.md) Karpathy wiki), record this project's service decisions there and index
-them from the root `CLAUDE.md`, so the next agent inherits the conventions instead of re-deriving them.
-
-1. **Find the article** `02-DOCS/wiki/stack/rust.md`, indexed in `02-DOCS/wiki/index.md` (the
-   Knowledge map index; root `CLAUDE.md` points to it).
-2. **If missing or stale**, create/update it with the project's real choices — the crate/workspace layout,
-   the runtime (tokio), the HTTP framework (axum 0.8), the error strategy (thiserror enum + IntoResponse
-   mapping), the DB layer (sqlx + pool), and tracing/concurrency defaults — then index it in
-   `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it).
-3. **Read it first on every use** and stay consistent; when a convention changes, update the article
-   (bump its `Updated` date) in the same change.
-
-No `02-DOCS/` layer? Skip silently (optionally suggest `harness`). Technical conventions are *recorded,
-not gated* — never block the task on this.
-
-## See Also
-
-Sibling skills (all resolve under `skills/`):
+Format and lint are build gates, not suggestions.
 
-- [`go`](../go/SKILL.md) - the structural twin: same write/review/test/ship service shape, GC + goroutines + multi-return errors instead of ownership + futures + `Result`.
-- [`secure-coding`](../secure-coding/SKILL.md) - threat modeling and language-agnostic authz/abuse/OWASP review (this skill keeps the Rust-specific controls).
-- [`postgresdb`](../postgresdb/SKILL.md) - SQL schema/index/query-plan tuning (this skill covers only the Rust-side sqlx query).
-- [`deployment`](../deployment/SKILL.md) - Docker multi-stage, CI, shipping infra (this skill ships only the Docker note + release-profile flags).
-- [`harness`](../harness/SKILL.md) - the `02-DOCS/` workspace wiki where per-project Rust conventions are recorded (see "Project grounding").
+## Project grounding (02-DOCS)
 
-Local references (read when):
+In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) wiki), the service decisions
+live in `02-DOCS/wiki/stack/rust.md`, indexed from `02-DOCS/wiki/index.md`. Read it first and stay
+consistent; if it is missing or stale, write the project's real choices there — crate/workspace layout,
+runtime (tokio), HTTP framework (axum 0.8), error strategy (thiserror enum + `IntoResponse` mapping), DB
+layer (sqlx + pool), tracing and concurrency defaults — bump its `Updated` date, and index it. No
+`02-DOCS/`? Skip silently. Conventions are *recorded, not gated* — never block the task on this.
 
-- `references/ownership.md` - move/borrow/clone deep dive, the borrow-checker error catalog, lifetimes, `'static`, `Cow`, smart-pointer tree, interior mutability.
-- `references/async-tokio.md` - runtime model, `JoinSet`/`select!`/channels, cancellation, `spawn_blocking`, `Send + Sync` across await, bounded-concurrency + retry helper.
-- `references/axum-service.md` - full skeleton: router, extractors, `State`, error->response, tower middleware, graceful shutdown, JSON helpers.
-- `references/testing.md` - unit/integration/doctests, `#[tokio::test]`, `tests/` HTTP tests against the Router, fakes/trait mocks, `cargo nextest`, `insta` snapshots.
+[`go`](../go/SKILL.md) is the structural twin: same write/review/test/ship service shape, GC +
+goroutines + multi-return errors instead of ownership + futures + `Result`. A desktop shell around a
+webview is [`tauri`](../tauri/SKILL.md), not this.

package/skills/sdd-init/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sdd-init
-description: "Use when calibrating an existing repo before running the rsc SDD flow: detecting stack, package manager, test runners, lint/type/build commands, monorepo signals, artifact store, execution mode, review budget, strict TDD capability, and project skill registry. Triggers: 'calibrate this repo for SDD', 'run sdd init', 'detect my test runner before implementing', 'set up SDD config', 'prepare this repo for spec-driven development', 'configure per-phase model routing', 'assign models per SDD phase', 'set up cheaper model for implementation'. NOT first-contact user/workspace bootstrap (init), NOT 01-TOOLS/02-DOCS scaffolding (harness), NOT writing a feature spec (specify)."
+description: "Use when calibrating an existing repo for the rsc SDD chain: detect stack, package manager, test runners and apply/verify commands, refresh the skill registry, and write the runtime config at 02-DOCS/wiki/sdd/config.yaml. NOT the dispatcher that routes SDD phases (that is `sdd`), NOT first-contact user/workspace bootstrap (that is `init`)."
 tags: [sdd, init, config, testing, registry]
 recommends: [sdd, specify, implement, verify]
 profiles: [core, full]
@@ -9,13 +9,13 @@ origin: risco
 
 # sdd-init — calibrate the repo before the SDD chain
 
-`sdd-init` is step zero for technical SDD work. It does not profile the user and it does not scaffold the harness. `init` owns first contact; `harness` owns `01-TOOLS/` and `02-DOCS/`. This skill reads the repo, detects how it should be built and tested, refreshes the cheap skill registry, and writes one durable config:
+Step zero for technical SDD work: read the repo, detect how it should be built and tested, refresh the cheap skill registry, and write one durable config:
 
 ```text
 02-DOCS/wiki/sdd/config.yaml
 ```
 
-That config is the runtime contract later phases read before choosing commands, TDD strictness, artifact paths, review budget or skill briefs.
+That config is the runtime contract later phases read before choosing commands, TDD strictness, artifact paths, review budget or skill briefs. `sdd` dispatches the phases that consume it, `init` owns first contact and user profiling, `harness` owns `01-TOOLS/` and `02-DOCS/` scaffolding. This skill only calibrates.
 
 ## Inputs
 
@@ -30,7 +30,7 @@ If `02-DOCS/` does not exist, create only the `02-DOCS/wiki/sdd/` path needed fo
 
 ## Preflight Choices
 
-Ask only when the answer changes behavior. At L0/L1 infer defaults and show them; at L2/L3 explain the trade-off.
+Ask only when the answer changes behavior; let the accompaniment level in the profile set how much you explain each trade-off.
 
 | Setting | Default | Options |
 | --- | --- | --- |
@@ -38,7 +38,7 @@ Ask only when the answer changes behavior. At L0/L1 infer defaults and show them
 | `artifact_store` | `02-DOCS/wiki/sdd` | Keep RSC artifacts in `02-DOCS`; do not create an `openspec/` parallel tree. |
 | `review_budget.line_budget` | `400` | Lower for solo tight review; higher only with explicit approval. |
 | `delivery_strategy.default` | `ask-on-risk` | `ask-on-risk`, `single-pr`, `autochain`, `exception`. |
-| `models.enabled` | `false` | Per-phase model routing is opt-in. Leave off unless the user asks for it; flipping it on is their call. |
+| `models.enabled` | `false` | Per-phase model routing is opt-in; leave off unless the user asks for it. |
 | `models.provider` | `anthropic` | Which provider the tiers resolve to. Set from the detected assistant when obvious, else `anthropic`. See `../sdd/references/model-routing.md` for other providers. |
 
 ## Detection
@@ -70,7 +70,7 @@ This writes:
 .rsc/skill-registry.md
 ```
 
-Later phases use this as a cheap index: id, trigger, tags, path, installed/available, hash. Do not load every skill into context. Select the few matching the phase and stack, then digest them into compact rules for subagents.
+Later phases use it as a cheap index — id, trigger, tags, path, installed/available, hash — to select the few skills matching the phase and stack and digest them into compact rules for subagents.
 
 ## Equip the repo — install the skills this stack needs
 
@@ -145,14 +145,9 @@ models:
   overrides: {}               # per-phase tier overrides set by the user
 ```
 
-The `models` block is the **per-phase model routing** profile: each phase declares a tier
-(`heavy`/`balanced`/`light`) and the tiers resolve to concrete models for `provider`. It ships
-**off** (`enabled: false`) — write it so the user can opt in, never switch models behind their
-back. The full protocol (how phases apply it, the per-assistant switch mechanism, the
-provider→model table) lives in `../sdd/references/model-routing.md`. Keep this block byte-for-byte
-in sync with that reference.
+The `models` block is the **per-phase model routing** profile: each phase declares a tier (`heavy`/`balanced`/`light`) and the tiers resolve to concrete models for `provider`. The full protocol — how phases apply it, the per-assistant switch mechanism, the provider→model table — lives in `../sdd/references/model-routing.md`. Keep this block byte-for-byte in sync with that reference.
 
-Preserve user edits if the file exists: update detected facts and leave comments/custom policy fields intact when possible. **Never flip `models.enabled` or drop `models.overrides` on re-calibration** — those are user choices; preserve them verbatim and only refresh `tiers`/`provider` if the user asks. If preservation is risky, write a proposed replacement next to it as `config.proposed.yaml` and ask.
+Preserve user edits if the file exists: update detected facts and leave comments/custom policy fields intact when possible. **Never flip `models.enabled` or drop `models.overrides` on re-calibration** — a calibration pass that silently switches the user's models is the one failure they cannot detect from the diff, so preserve both verbatim and only refresh `tiers`/`provider` if the user asks. If preservation is risky, write a proposed replacement next to it as `config.proposed.yaml` and ask.
 
 ## Result Envelope
 
@@ -186,7 +181,7 @@ End with the standard SDD result envelope:
 | "I'll skip config and remember the commands in chat." | Chat is not source of truth. Write `config.yaml`. |
 | "No test command detected, but I'll still say strict TDD is active." | Strict TDD needs a runner. Record the gap. |
 | "Load all skills so the agent has context." | That pollutes context. Use registry -> selected skills -> compact rules. |
-| "This is the same as init." | No. `init` profiles user/workspace; `sdd-init` calibrates technical SDD runtime. |
+| "This is the same as init." | No. `init` profiles user/workspace, `sdd` dispatches the phases, `sdd-init` calibrates the technical SDD runtime they both rely on. |
 | "Create openspec/ because Gentle does." | RSC uses `02-DOCS/wiki/sdd/` as source of truth. |
 
 ## Next