@ericrisco/rsc 0.1.56 → 0.1.58

package/skills/market-research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: market-research
-description: "Use when you need a defensible picture of a MARKET as a whole — sizing it with TAM/SAM/SOM, cutting it into reachable segments, and proving demand is real and moving — with a dated source behind every number. Triggers: 'how big is the market for X', 'size this market', 'what's our TAM', 'is there real demand for this', 'who are the segments', 'where's the beachhead', 'sanity-check this TAM before the raise', 'top-down or bottom-up', '¿qué tamaño tiene el mercado de X', 'calcula el TAM', 'hay demanda real para esto', 'quina mida té aquest mercat'. NOT profiling specific named rivals and their moves (that is competitor-watch), NOT building a named list of accounts to sell to (that is lead-gen)."
+description: "Use when a MARKET as a whole needs a defensible picture — TAM/SAM/SOM sized top-down AND bottom-up until the two converge, cut into reachable segments with one named beachhead, demand proven real, and a dated source behind every figure. NOT profiling named rivals and their moves (that is `competitor-watch`), NOT building a list of accounts to sell to (that is `lead-gen`)."
 tags: [market-research, tam-sam-som, market-sizing, segmentation, demand-signals, jtbd, opportunity]
 recommends: [competitor-watch, lead-gen, pitch-deck, financial-model, pricing, forecasting, content-engine]
 origin: risco
@@ -14,22 +14,19 @@ The test of this work is not the number. It is **whether someone else can audit
 
 ## The hard stop: no named entities
 
-This skill produces understanding of a market **as a whole** — never a named buyer you can call today, never a named competitor dossier. The moment the ask turns into "who specifically," stop and route:
-
-- "Give me 200 fintech accounts with the VP Eng contact" → that is a sales list → `../lead-gen/SKILL.md`.
-- "Profile Competitor X — their tiers, gaps, recent launches" → that is a rival dossier → `../competitor-watch/SKILL.md`.
+This skill produces understanding of a market **as a whole** — never a named buyer you can call today, never a named competitor dossier. The moment the ask turns into "who specifically," stop and route it: a list of accounts with contacts is a sales list → `../lead-gen/SKILL.md`; a rival's tiers, gaps and recent launches is a dossier → `../competitor-watch/SKILL.md`.
 
 Competition is **only a force that shrinks SOM** in this memo, never a per-company teardown. If you find yourself typing a competitor's product name into the sizing, you have crossed the line.
 
 ## The three jobs
 
-| Job | One governing rule | Failure if skipped |
-| --- | --- | --- |
-| **Size it** | Never ship a number without a second, independent method | A lone figure is unfalsifiable; readers discount it |
-| **Segment it** | Cut by the *job buyers hire you for*, then prove the slice is reachable AND distinct | A market with no beachhead is a market you can't enter |
-| **Read demand** | Secondary to form the hypothesis, primary to decide it | You confirm your own bias with stale reports |
+| Job | One governing rule |
+| --- | --- |
+| **Size it** | Never ship a number without a second, independent method |
+| **Segment it** | Cut by the *job buyers hire you for*, then prove the slice is reachable AND distinct |
+| **Read demand** | Secondary to form the hypothesis, primary to decide it |
 
-Do them in order — sizing tells you what to segment, segments tell you where to read demand. The artifact at the end ties all three together with a sources table. That memo is what `scripts/verify.sh` lints.
+Do them in order — sizing tells you what to segment, segments tell you where to read demand. The artifact at the end ties all three together with a sources table.
 
 ## Job 1 — Size it (triangulate or it's a guess)
 
@@ -39,7 +36,6 @@ Two instruments, two different errors. Run **both** and force them to agree.
 | --- | --- | --- | --- | --- |
 | **Top-down** | A published industry figure (Gartner/IDC/Statista, e.g. "$70B CRM market") | `industry size × your segment share %` | Fast, anchors to a named source | Inherits and amplifies the report's error; easy to hand-wave the share % |
 | **Bottom-up** | Your customers + price | `ACV × number of ICP-fitting accounts` | Grounded in your own pricing; survives investor scrutiny | Slow; needs a real ICP and a real account count |
-| **Triangulation** | BOTH of the above | Run both, force them to agree | The actual credibility signal | Skipping it — a lone number is a guess |
 
 ### The triangulation gate
 
@@ -58,7 +54,7 @@ Good  Bottom-up:  960 ICP accounts × $50K ACV       = $48M
 - **SAM** — the slice your business model + geography can actually serve.
 - **SOM** — the slice you can realistically capture near-term, given competition and sales capacity.
 
-The funnel `SAM ≈ 20% of TAM`, `SOM ≈ 10% of SAM` is an **illustrative example to defend, not a constant to assume.** Derive SAM from your real reach (model, geography, language) and SOM from the competitive pressure and your sales capacity — then state why. Worked top-down and bottom-up calculations, the convergence math, and the full memo template live in `references/sizing-playbook.md`.
+The funnel `SAM ≈ 20% of TAM`, `SOM ≈ 10% of SAM` is an **illustrative example to defend, not a constant to assume.** Derive SAM from your real reach (model, geography, language) and SOM from the competitive pressure and your sales capacity — then state why. Worked top-down and bottom-up calculations, the convergence math, the SAM-then-SOM derivation logic, and the full memo template with its sources/provenance schema live in `references/sizing-playbook.md`.
 
 ## Job 2 — Segment it (reachable AND distinct, with a named beachhead)
 
@@ -108,15 +104,15 @@ This is exactly what `scripts/verify.sh` checks. Keep it Markdown so the linter
 | "$50B market" with no source or year | Cite the report + access date for every figure | Undated/unsourced = a guess; markets move fast |
 | Top-down and bottom-up are 4× apart, pick the bigger | Re-check inputs until they converge ≤~20% | 3–5× divergence means broken assumptions, not a choice |
 | Convert a Google Trends curve into a market size | Pair with absolute-volume tools before sizing | Trends is RELATIVE interest, never absolute volume |
-| Segment by demographics alone | Add JTBD/behavioral; name a reachable beachhead | Demographics miss *why* people actually buy |
+| Segment by demographics alone | Add JTBD/behavioral; name a reachable beachhead | Demographics miss *why* people buy, and a market with no beachhead is one you can't enter |
 | Treat SAM/SOM as fixed 20%/10% of TAM | Derive SAM from reach, SOM from competition + capacity | Those ratios are illustrative, not constants |
 | Name specific competitor products in the memo | Treat competition as a SOM-shrinking force | A dossier is scope creep — hand to competitor-watch |
 | List named target accounts as "the market" | Hand the segment to lead-gen to build the list | That is a sales list, not market understanding |
-| All secondary data, no primary check on the decisive question | Use interviews/survey to fill the gap that decides | Stale or misaligned reports mislead the call |
+| All secondary data, no primary check on the decisive question | Use interviews/survey to fill the gap that decides | Stale or misaligned reports mislead the call — you just confirm your own bias |
 
 ## Verify
 
-The memo is a checkable artifact, so `scripts/verify.sh` lints a produced memo file (read-only — it never edits) for the three things that keep "market sizing" honest:
+The memo is a checkable artifact, so `scripts/verify.sh` lints a produced memo file (read-only — it never edits) for the three things above that keep "market sizing" honest: the numeric `SOM ≤ SAM ≤ TAM` nesting, **both** methods plus a stated convergence/divergence note (one method alone fails), and a citation **and** date on every load-bearing figure.
 
 ```bash
 ./scripts/verify.sh                     # scan ./ for *memo*/*market*.md
@@ -125,7 +121,7 @@ The memo is a checkable artifact, so `scripts/verify.sh` lints a produced memo f
 ./scripts/verify.sh --strict            # treat warnings as failures (CI gate)
 ```
 
-It asserts: (a) **TAM, SAM, SOM** all present with parseable numeric values and the nesting `SOM ≤ SAM ≤ TAM` holds; (b) evidence of **both** a top-down and a bottom-up figure plus a stated **convergence/divergence** note — fails if only one method is present; (c) a **sources** section where each load-bearing figure carries a citation/URL AND a date. It exits `0` on a clean or empty target — a missing memo is a skip, never a false failure. The memo schema it enforces is documented in `references/sizing-playbook.md`.
+It exits `0` on a clean or empty target — a missing memo is a skip, never a false failure.
 
 ## Hand-offs
 
@@ -138,8 +134,3 @@ The memo is the start of a chain. When it is done, route:
 - Set the ACV the bottom-up math depends on → `../pricing/SKILL.md`.
 - Project the demand series forward from history → `../forecasting/SKILL.md`.
 - Act on the keyword/topic demand signals → `../content-engine/SKILL.md`.
-
-## references/
-
-- `references/sizing-playbook.md` — worked top-down and bottom-up calculations side by side, the triangulation convergence math (≤~15–20% credible, 3–5× broken), the SAM-then-SOM derivation logic, and the full market-memo template including the mandatory sources/provenance table schema.
-- `references/demand-signals.md` — the signal-source catalog (Google Trends + its relative-volume caveat, Exploding Topics, Statista, government/industry data, primary survey/interview design) and a source-grading rubric for vetting secondary data by recency and credibility.

package/skills/market-research/evals/cases.yaml

@@ -2,7 +2,7 @@ skill: market-research
 
 should_trigger:
   - prompt: "How big is the market for AI legal-research tools in Spain?"
-    why: Core sizing request — "how big is the market for X" is the central trigger.
+    why: Core sizing request for a whole market — Job 1, the central case for this skill.
   - prompt: "Sanity-check this TAM before our seed raise — does $2B hold up?"
     why: Non-obvious; cross-checking an existing number IS the triangulation core, not deck design or modeling.
   - prompt: "Cut our addressable market into segments and tell me which one to attack first."
@@ -12,9 +12,9 @@ should_trigger:
   - prompt: "Should we size this top-down from the industry report or bottom-up from our customers?"
     why: Non-obvious; the top-down-vs-bottom-up choice and triangulation gate are this skill's method, not a generic data pull.
   - prompt: "¿Qué tamaño tiene el mercado de software de reservas para restaurantes y cuál es el TAM/SAM/SOM?"
-    why: Spanish trigger for the full sizing job — TAM/SAM/SOM explicitly requested.
+    why: Spanish-language ask for the full sizing job — TAM/SAM/SOM explicitly requested.
   - prompt: "Quina mida té el mercat d'apps de reserves i hi ha demanda real?"
-    why: Catalan trigger combining market size and demand validation — both core jobs.
+    why: Catalan-language ask combining market size and demand validation — both core jobs.
 
 should_not_trigger:
   - prompt: "Profile Competitor X — their pricing tiers, feature gaps, and recent product launches."

package/skills/nestjs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nestjs
-description: "Use when building or structuring a NestJS backend — feature modules, providers, controllers, DI wiring, and the cross-cutting layer (guards, interceptors, pipes, exception filters) — including binding-scope and request-lifecycle decisions and Nest-specific testing. Triggers: 'create a NestJS module', 'wire a custom provider with useFactory', 'APP_GUARD vs @UseGuards on the controller', 'my request-scoped provider is undefined in a guard', 'A circular dependency has been detected at bootstrap', 'mock a repository provider with overrideProvider', 'monta un módulo de Nest', 'guard de autenticación JWT en NestJS'. NOT a bare Express/Node service with no DI (that is nodejs)."
+description: "Use when building or structuring a NestJS backend — feature modules, providers and DI wiring, provider scopes and request-lifecycle order, where to bind guards/pipes/interceptors/filters, and testing with Test.createTestingModule. NOT a bare Express/Fastify service with no DI (that is `nodejs`), NOT framework-agnostic REST design (that is `api-design`)."
 tags: [nestjs, nodejs, backend, dependency-injection, guards, pipes, testing, typescript]
 recommends: [nodejs, typescript, api-design, prisma-orm, testing-web]
 origin: risco
@@ -10,15 +10,7 @@ origin: risco
 
 Build server-side Node apps the way NestJS intends: feature modules, providers wired through the DI container, controllers, and a cross-cutting layer bound at a deliberate scope. This skill is about Nest-specific mechanics — how DI scopes resolve, what order the request lifecycle runs in, where to bind guards/pipes/interceptors/filters, and how to test it with `Test.createTestingModule`.
 
-## Use this when
-
-- Scaffolding or extending a Nest app: new module, controller, provider, resolver.
-- Wiring DI: `useClass` / `useValue` / `useFactory` / `useExisting`, injection tokens, `forwardRef`, dynamic modules (`forRoot` / `forRootAsync`).
-- Adding cross-cutting behavior and deciding global vs controller vs route binding.
-- "Why is my request-scoped provider undefined" / "circular dependency detected at bootstrap".
-- Unit tests with mock providers and e2e tests with Supertest against the real Nest app.
-
-## Not this when
+## Not this — route instead
 
 - Bare Express/Fastify/`http` service, no `@Module`/`@Injectable` → `../nodejs/SKILL.md`. Nest starts the moment the DI container appears.
 - REST resource modeling, versioning, status codes, idempotency (framework-agnostic) → `../api-design/SKILL.md`. Nest is where you *implement* those decisions.

package/skills/nodejs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nodejs
-description: "Use when building or structuring a plain Node.js / Express backend service — project layout, async correctness, central error handling, config validation, and graceful shutdown — the runtime and HTTP service, not a DI framework. Triggers: 'set up an Express 5 service', 'my async route error returns 200 with an empty body', 'where do controllers vs services go', 'centralize error handling middleware', 'shut down cleanly on SIGTERM without dropping requests', 'why does one unhandled promise rejection crash my server', 'monta un backend con Express y manejo de errores', 'apaga el servidor sin perder peticiones en vuelo'. NOT NestJS DI/modules/guards (that is nestjs); NOT the TS type system/tsconfig (that is typescript); NOT REST contract/versioning (that is api-design)."
+description: "Use when building or operating a plain Node.js / Express 5 backend service: project layout, async correctness, central error middleware, fail-fast config, graceful shutdown on SIGTERM. NOT DI modules/providers/guards (that is `nestjs`), NOT the type system or tsconfig (that is `typescript`), NOT REST contract design (that is `api-design`)."
 tags: [nodejs, express, backend, async, error-handling]
 recommends: [nestjs, typescript, api-design, error-handling, postgresdb]
 origin: risco
@@ -8,24 +8,15 @@ origin: risco
 
 # Node.js backend services
 
-Stand up a plain Node.js HTTP/JSON service — `node:http` or Express 5 — that a person can read, test, and operate without a DI framework. This skill is about the runtime and the request lifecycle: how to lay out the code, how to keep async correct, how errors become status codes, how config fails fast, and how the process dies cleanly. The contract shape, the type system, and the data layer live elsewhere (see the boundaries below).
+Stand up a plain Node.js HTTP/JSON service — `node:http` or Express 5 — that a person can read, test, and operate without a DI framework. This skill is about the runtime and the request lifecycle: how to lay out the code, how to keep async correct, how errors become status codes, how config fails fast, and how the process dies cleanly. The contract shape, the type system, and the data layer live elsewhere (see the boundary below).
 
-## Use this when
+## Boundary
 
-- Standing up a new HTTP/JSON service on Node with Express 5 (or bare `node:http`).
-- Structuring routes / controllers / services / repositories in a non-DI app.
-- Fixing async bugs: floating promises, swallowed errors, callbacks not awaited.
-- Centralizing error handling and the 404/500 contract in one place.
-- Graceful shutdown on SIGTERM, env validation at boot, the request lifecycle.
-- Choosing CommonJS vs ESM and pinning a runtime.
-
-## Not this when
-
-- The app is built around `@Module` / `@Injectable` / DI providers, guards, interceptors, pipes, exception filters → `../nestjs/SKILL.md`. Nest starts the moment the DI container appears; route away then, do not half-build it here.
-- Pure TypeScript type system, generics, `tsconfig` → `../typescript/SKILL.md`. This skill uses TS but does not teach types.
-- REST resource modeling, versioning, pagination, status-code semantics (framework-agnostic) → api-design. This skill *wires* the handlers; api-design decides the contract.
-- Schema, queries, connection pool, migrations → `../postgresdb/SKILL.md` / prisma-orm / drizzle-orm. *Calling* a repository stays here; designing the table does not.
-- Containerizing / shipping → docker / deployment. Choosing the logging/metrics/tracing stack → observability. This skill emits structured logs and a shutdown hook; it does not own the pipeline.
+- The app is built around `@Module` / `@Injectable` / DI providers, guards, interceptors, pipes, exception filters → [`nestjs`](../nestjs/SKILL.md). Nest starts the moment the DI container appears; route away then, do not half-build it here.
+- Pure TypeScript type system, generics, `tsconfig` → [`typescript`](../typescript/SKILL.md). This skill uses TS but does not teach types.
+- REST resource modeling, versioning, pagination, status-code semantics (framework-agnostic) → [`api-design`](../api-design/SKILL.md). This skill *wires* the handlers; api-design decides the contract. Cross-cutting error taxonomy → [`error-handling`](../error-handling/SKILL.md).
+- Schema, queries, connection pool, migrations → [`postgresdb`](../postgresdb/SKILL.md) / [`prisma-orm`](../prisma-orm/SKILL.md) / [`drizzle-orm`](../drizzle-orm/SKILL.md). *Calling* a repository stays here; designing the table does not.
+- Containerizing / shipping → [`docker`](../docker/SKILL.md) / [`deployment`](../deployment/SKILL.md). Choosing the logging/metrics/tracing stack → [`observability`](../observability/SKILL.md). This skill emits structured logs and a shutdown hook; it does not own the pipeline.
 
 ## Decide first
 
@@ -33,7 +24,7 @@ Pick the runtime shape before writing code — the wrong choice is expensive to
 
 | Situation | Choice | Why |
 | --- | --- | --- |
-| Needs DI/modules, large team, heavy cross-cutting | route to `../nestjs/SKILL.md` | Don't reinvent a DI container by hand |
+| Needs DI/modules, large team, heavy cross-cutting | route to [`nestjs`](../nestjs/SKILL.md) | Don't reinvent a DI container by hand |
 | Small/medium JSON API, want middleware + routing | Express 5 | Mature, async errors auto-forward (v5) |
 | One tiny endpoint, zero deps, a healthcheck | `node:http` | No dependency surface to maintain |
 | A library, not a server | not this skill | No request lifecycle to manage |
@@ -158,7 +149,7 @@ app.get("/users/:id", async (req, res) => {
 });
 ```
 
-The error handler placed before the route never sees the throw, so the response is whatever was half-written. Put it last. See `references/express5-migration.md` for the full v4→5 breaking-change checklist and the legacy v4 `asyncHandler` wrapper.
+The error handler placed before the route never sees the throw, so the response is whatever was half-written. Put it last. See [`references/express5-migration.md`](references/express5-migration.md) for the full v4→5 breaking-change checklist, the middleware-order diagram, and the legacy v4 `asyncHandler` wrapper.
 
 ## Config & secrets
 
@@ -185,7 +176,7 @@ On SIGTERM the orchestrator gives you a brief window to finish. Drop nothing.
 4. Close the DB pool and other resources.
 5. `process.exit(0)`, with a force-exit timer as a backstop if drain stalls.
 
-Expose `/healthz` (liveness — is the process up) separately from `/readyz` (readiness — should it receive traffic). They answer different questions; conflating them causes both false restarts and dropped requests during deploys. The full copy-pasteable `server.ts` lives in `references/graceful-shutdown.md`.
+Expose `/healthz` (liveness — is the process up) separately from `/readyz` (readiness — should it receive traffic). They answer different questions; conflating them causes both false restarts and dropped requests during deploys. The complete copy-pasteable `server.ts` — signal handlers, `AbortController`, readiness gate, force-exit backstop — lives in [`references/graceful-shutdown.md`](references/graceful-shutdown.md).
 
 ```ts
 // server.ts (sketch — full version in references/)
@@ -230,13 +221,9 @@ test("404 returns the error contract", async () => {
 | `catch (e) {}` then continue | Swallows the failure, masks the bug | Re-throw, or map to an `AppError` |
 | `process.exit()` without draining | Drops in-flight requests on deploy | SIGTERM → `server.close()` → abort → exit |
 | Global `unhandledRejection` as control flow | Hides bugs, leaves process in a bad state | Log + exit there; fix the floating promise |
-| Assuming Express 4 defaults | v5: `urlencoded` `extended:false`, `static` `dotfiles:"ignore"` | Read `references/express5-migration.md` |
+| Assuming Express 4 defaults | v5: `urlencoded` `extended:false`, `static` `dotfiles:"ignore"` | Read [`references/express5-migration.md`](references/express5-migration.md) |
 | Leaking stack/message in prod | Information disclosure | Stack only when `NODE_ENV !== "production"` |
 
-## References & siblings
-
-- `references/express5-migration.md` — full Express 4→5 breaking changes, middleware-order diagram, the legacy v4 `asyncHandler` wrapper.
-- `references/graceful-shutdown.md` — complete `server.ts`: signal handlers, `AbortController`, readiness gate, force-exit backstop.
-- DI/modules/guards → `../nestjs/SKILL.md`. Type system/tsconfig → `../typescript/SKILL.md`. Data layer → `../postgresdb/SKILL.md`. Contract design → api-design. Cross-cutting error taxonomy → error-handling.
+## Verify
 
 `scripts/verify.sh` statically lints a produced repo for these rules (4-arg error handler last, no `listen()` in `app.ts`, `engines.node` supported, floating-promise heuristic). Advisory; hard-fails only on `listen()` in `app.ts` or a missing error handler.

package/skills/prisma-orm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prisma-orm
-description: "Use when modeling data or writing type-safe queries with Prisma ORM in TypeScript and hitting its classic problems: N+1 on relations, over-fetching with fat include, an unbounded findMany scanning the whole table, the v7 'requires either adapter or accelerateUrl' error, or a Prisma 6 to 7 upgrade. Owns schema.prisma, the prisma-client generator, prisma.config.ts, the Prisma Client query API, and Prisma Migrate. Triggers: 'PrismaClient requires either adapter or accelerateUrl', 'client is not in node_modules anymore', 'relationLoadStrategy join vs query', 'migrate dev vs migrate deploy in CI', 'findMany returns the whole table', 'modela el esquema de usuarios y pedidos con Prisma', 'migració de Prisma a la versió 7'. NOT the schema-as-TS SQL-builder ORM (that is drizzle-orm), NOT cross-cutting zero-downtime migration strategy (that is db-migrations), NOT Postgres server tuning and EXPLAIN (that is postgresdb)."
+description: "Use when modeling data or writing type-safe queries with Prisma ORM in TypeScript — `schema.prisma`, `prisma.config.ts`, the generated Prisma Client, and Prisma Migrate, including the v6 to v7 upgrade. NOT schema-as-TS with a SQL builder (that is `drizzle-orm`), NOT ORM-agnostic zero-downtime migration (that is `db-migrations`), NOT Postgres engine tuning (that is `postgresdb`)."
 tags:
   - prisma
   - prisma-orm
@@ -286,8 +286,8 @@ Rules with teeth:
 
 Failed-migration recovery, baselining an existing database, and the full Prisma 6 to 7
 upgrade are in `references/migrations-and-v7-upgrade.md`. For ORM-independent evolution
-strategy (expand/contract, dual-write, zero-downtime backfills) that is the `db-migrations`
-skill.
+strategy (expand/contract, dual-write, zero-downtime backfills) that is
+`../db-migrations/SKILL.md`.
 
 ## Anti-patterns
 
@@ -311,10 +311,3 @@ Run `scripts/verify.sh <path>` to statically check emitted artifacts: it confirm
 `prisma-client` generator + `output`, an adapter on the constructor, and flags
 `$queryRawUnsafe` injection, `binaryTargets`, unbounded `findMany`, and wrong-ORM
 contamination. Read-only; no database connection.
-
-## References
-
-- `references/queries-and-performance.md` — query cookbook, `relationLoadStrategy` matrix,
-  transactions, generated types, the perf checklist, and the raw-SQL safety matrix.
-- `references/migrations-and-v7-upgrade.md` — migrate workflow detail, failed-migration
-  recovery, baselining, and the full Prisma 6 to 7 upgrade.

package/skills/prisma-orm/evals/cases.yaml

@@ -21,8 +21,8 @@ should_trigger:
     why: Non-obvious v7 change — generated output path replaces the node_modules import.
   - prompt: "Necessito fer la migració de Prisma a la versió 7, què he de canviar a schema.prisma i al client?"
     why: >
-      Catalan phrasing matching the description's stated coverage — the v6 to 7 upgrade
-      (generator rename, output, adapter, prisma.config.ts) is explicitly owned here.
+      Catalan phrasing of the v6 to 7 upgrade (generator rename, output, adapter,
+      prisma.config.ts), which this skill owns.
 
 should_not_trigger:
   - prompt: "Set up the same schema using Drizzle's pgTable and drizzle-kit"

package/skills/procurement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: procurement
-description: "Use when a small operator must decide what to buy and from whom — pick a supplier/vendor, write an RFI/RFQ/RFP that gets comparable bids back, compare quotes on total cost not sticker price, negotiate price and payment terms, judge single-source risk, or build a vendor scorecard for quarterly review. Triggers: 'help me pick a supplier for X', 'write an RFQ for 5,000 units', 'which of these quotes is actually cheapest over three years', 'should I take the 2/10 net 30 early-payment discount', 'we buy a critical part from one supplier — how risky is that', 'build a supplier scorecard', 'compara estos proveedores / negociar condiciones de pago', 'compara aquests proveïdors / negociar condicions amb el proveïdor'. NOT signing the binding purchase agreement or redlining liability/IP clauses (that is contracts), NOT the price you charge your own customers (that is pricing), NOT counting or reordering the stock once it arrives (that is inventory)."
+description: "Use when a small operator must choose what to buy and from whom: pick a supplier, write an RFI/RFQ/RFP that returns comparable bids, score quotes on total cost of ownership, negotiate price and payment terms, or judge single-source risk. NOT redlining the purchase agreement (that is `contracts`), NOT the price you charge customers (that is `pricing`), NOT stock once it lands (that is `inventory`)."
 tags: [procurement, sourcing, suppliers, rfq, negotiation, vendor-management]
 recommends: [contracts, pricing, inventory, logistics-ops, invoicing, cost-tracking]
 origin: risco
@@ -172,8 +172,3 @@ You own the decision and the deal. The moment it becomes something else, route:
 - Tracking ongoing SaaS/subscription spend after a renewal decision → `../cost-tracking/SKILL.md`.
 
 > Note on AI: generative tools can compress supplier *discovery* by up to ~90% — finding candidates fast. They do not replace the weighting, TCO model, risk segmentation, or negotiation. Use AI to widen the shortlist; keep the judgment human and on paper.
-
-## references/
-
-- `references/sourcing-requests.md` — copy-ready RFI/RFQ/RFP skeletons with the mandatory comparable-bid sections, plus invite and award/regret email templates.
-- `references/scorecard-and-tco.md` — weighted-scorecard template, worked TCO comparison layout, supplier performance scorecard, SRM-cadence-by-quadrant table, and re-source trigger thresholds.

package/skills/procurement/evals/cases.yaml

@@ -12,9 +12,9 @@ should_trigger:
   - prompt: "We buy a critical component from only one supplier — how worried should I be?"
     why: Single/sole-source concentration risk and the backup-plan requirement.
   - prompt: "Negociar mejores condiciones de pago con nuestro proveedor."
-    why: Spanish trigger — payment-terms negotiation, trading a concession for extended terms.
+    why: Asked in Spanish — payment-terms negotiation, trading a concession for extended terms.
   - prompt: "Compara aquests proveïdors i munta una scorecard ponderada per decidir."
-    why: Catalan trigger — weighted-scorecard supplier comparison.
+    why: Asked in Catalan — weighted-scorecard supplier comparison.
 
 should_not_trigger:
   - prompt: "Draft and redline the purchase agreement so we can sign it."

package/skills/reporting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: reporting
-description: "Use when you need a recurring report that ships to stakeholders on a cadence — a weekly team digest, monthly exec pack, quarterly board summary, or recurring client performance report — and it must go out reliably without a human in the loop. Symptoms: a standing metrics email keeps breaking or shows stale numbers, the Monday digest is hand-assembled every week, leadership asks for 'the same report but every month', or a client expects a PDF on a schedule. Triggers: 'set up a weekly automated report emailed to the exec team', 'build a monthly PDF report for our biggest client on a schedule', 'send the board a quarterly summary every quarter', 'our Monday metrics email keeps going out with last week's numbers — make it reliable', 'automatiza un informe mensual para dirección', 'munta un informe setmanal automàtic per al comitè'. NOT a live screen people open to slice metrics (that is dashboard), NOT deciding which KPIs to track (that is kpi-framework), NOT a one-off investigation (that is analytics)."
+description: "Use when a recurring report must ship itself on a cadence — weekly digest, monthly exec pack, board pack — via a fetch→narrate→render→deliver pipeline with a schedule and a freshness gate. NOT a live view people slice (that is `dashboard`), NOT picking which KPIs to track (that is `kpi-framework`), NOT a one-off investigation (that is `analytics`)."
 tags: [reporting, automated-reports, recurring, stakeholder-reporting, scheduled-delivery, data-analytics]
 recommends: [dashboard, kpi-framework, analytics, automation-flows, email-connector, spreadsheet-ops, google-workspace, notion-connector, github-actions]
 origin: risco
@@ -10,9 +10,10 @@ origin: risco
 
 A report is a **push** artifact: a fixed snapshot that lands in someone's inbox or shared drive on a
 cadence, the same shape every period, with no human assembling it. That is the whole job. If a human
-opens a live view to slice numbers themselves, that is **pull** — a dashboard, not a report. Hold that
-line; almost every failed "reporting" project is a dashboard wearing a report's name, or a report
-nobody can trust because the numbers went stale and no one noticed.
+opens a live view to slice numbers themselves, that is **pull** — a
+[`dashboard`](../dashboard/SKILL.md), not a report. Hold that line; almost every failed "reporting"
+project is a dashboard wearing a report's name, or a report nobody can trust because the numbers went
+stale and no one noticed.
 
 Your deliverable is a **runnable pipeline**, not advice: a template, a generation script, a schedule,
 and a delivery step, with a freshness gate so it fails loud instead of shipping yesterday's numbers.
@@ -32,24 +33,23 @@ is a number no one can defend.
 | **Owner** | Who gets paged when it breaks | a named person, not "the team" |
 
 Rule: you **consume** an agreed metric set — you do not adjudicate which KPIs matter. If the ask is
-"which metrics should we even track?", that is kpi-framework, not this skill. The contract names the
-source and its owner so a wrong number has an address.
+"which metrics should we even track?", that is [`kpi-framework`](../kpi-framework/SKILL.md), not this
+skill. The contract names the source and its owner so a wrong number has an address.
 
 ## Decide: push report vs live dashboard (this branches — settle it first)
 
-Audiences want a consistent, citable snapshot for the period far more often than a live feed; that is
-why scheduled push beats a dashboard for exec summaries, weekly reviews, and finance close packs.
+Audiences want a citable snapshot for the period more often than a live feed — that is why push wins
+for exec summaries, weekly reviews, and finance close packs.
 
 | Signal in the ask | Route |
 | --- | --- |
 | "Same summary, every week/month/quarter" | **reporting** (here) |
 | "Consistent snapshot the board can cite in a meeting" | **reporting** (here) |
 | "It must arrive even if no one logs in" | **reporting** (here) |
-| "A screen people open to filter/drill live" | **dashboard** |
-| "Self-serve, slice by region/date on demand" | **dashboard** |
+| "A screen people open to filter/drill live" | [`dashboard`](../dashboard/SKILL.md) |
+| "Self-serve, slice by region/date on demand" | [`dashboard`](../dashboard/SKILL.md) |
 
-When both are wanted, build the report; let it link to the dashboard as a "go deeper" footer. Do not
-email a dashboard link and call it a report — see the anti-patterns table.
+When both are wanted, build the report and let it link to the dashboard as a "go deeper" footer.
 
 ## Pick the artifact format
 
@@ -120,7 +120,7 @@ Bad → Good, the difference that decides whether the report is useful:
 - **Bad:** a table row `Revenue | 248,300 | 201,400`. The reader must do the math and guess if it matters.
 - **Good:** "Revenue up 23.3% WoW (€248,300 from €201,400) — investigate: driven by the enterprise renewal that won't recur next week."
 
-Never ship a raw metric dump with no narrative. The numbers are the evidence; the sentence is the report.
+The numbers are the evidence; the sentence is the report.
 
 ## Schedule + reliability gate (where reports actually die)
 
@@ -145,7 +145,8 @@ does not teach scheduling in general. The actual transport (SMTP/Gmail send) bel
 
 - [ ] **Freshness gate before send** — assert the source is newer than the last period; if stale, do
       NOT send, raise instead. A report that consumes dirty data is not this skill's job to clean —
-      that is data-cleaning; this gate only refuses to ship known-stale numbers.
+      that is [`data-cleaning`](../data-cleaning/SKILL.md); this gate only refuses to ship
+      known-stale numbers.
 - [ ] **Fail loud** — on any error, alert the owner (the report not arriving is itself a silent failure).
 - [ ] **Idempotent run** — re-running for the same period produces the same artifact, no duplicate send.
 - [ ] **Dead-report cleanup** — if no one opened the last N editions, kill the schedule. Unread reports
@@ -161,18 +162,15 @@ does not teach scheduling in general. The actual transport (SMTP/Gmail send) bel
 | Raw metric dump, no narrative | Reader does the math, misses what changed, stops opening it | Exec summary + 3 takeaways + a "so what" per section |
 | Schedule with no failure alert | A broken job is invisible for weeks; the report just stops | Fail loud to the named owner on any error |
 | A template forked per recipient | Layout change must be made N times; they drift | Single template scoped by `params` |
-| Redefining KPIs inside the report | The report quietly becomes the metric authority, numbers diverge | Consume an agreed set; defer definition to kpi-framework |
+| Redefining KPIs inside the report | The report quietly becomes the metric authority, numbers diverge | Consume an agreed set; defer definition to [`kpi-framework`](../kpi-framework/SKILL.md) |
 | Unpinned WeasyPrint / render lib | A minor bump reflows the board pack with no warning | Pin (WeasyPrint 68.1) and re-check PyPI before changing |
 | Hand-assembling the digest weekly | It breaks the week the owner is on leave | Automate the pipeline end to end; a human only reads it |
 
 ## Verify
 
 Run `scripts/verify.sh` (read-only; pass a path to a generated pipeline directory, or run in it). It
-confirms a Jinja2 template exists and renders against a sample context without error, that the
-generation script produces a non-empty PDF/HTML artifact, that a schedule definition exists (a crontab
-line or a `.github/workflows/*.yml` with a `schedule:` block), and that a delivery step is wired. It
-soft-warns if no freshness/failure gate is detected. On an empty/clean target it exits 0 — nothing to
-check is not a failure.
-
-References: [`pipeline.md`](references/pipeline.md) — full template, chart embed, per-recipient loop,
-GitHub Actions `schedule:` YAML, freshness gate, and failure alert.
+confirms a Jinja2 template renders against a sample context without error, the generation script
+produces a non-empty PDF/HTML artifact, a schedule definition exists (a crontab line or a
+`.github/workflows/*.yml` with a `schedule:` block), and a delivery step is wired. It soft-warns if no
+freshness/failure gate is detected, and exits 0 on an empty/clean target — nothing to check is not a
+failure.

package/skills/ruby/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ruby
-description: "Use when writing idiomatic Ruby outside Rails — plain scripts, CLIs, gems, libraries — or refactoring imperative loops into Enumerable chains, designing module mixins, packaging with Bundler, deciding whether metaprogramming is worth it, or setting up Minitest/RSpec. Triggers: 'write this in Ruby', 'refactor this loop with map/reduce', 'build a gem', 'gemspec / Gemfile.lock', 'method_missing or define_method?', 'Minitest vs RSpec', 'FrozenError after Ruby 3.4 upgrade', 'mixin vs inheritance', 'escribir una gema en Ruby', 'refactoritzar amb blocs'. NOT Rails/ActiveRecord/controllers (that is rails)."
+description: "Use when writing or refactoring plain Ruby outside Rails — scripts, CLIs, gems, libraries: Enumerable chains and blocks, module mixins and value objects, Bundler/gemspec packaging, whether metaprogramming earns its keep, Minitest or RSpec, Ruby 3.4/4.0 frozen-string hygiene. NOT Rails, ActiveRecord, or ActiveSupport idioms (that is `rails`)."
 tags: [ruby, gems, bundler, metaprogramming, rspec, minitest, enumerable]
 recommends: [rails, testing-web, secure-coding]
 profiles: []
@@ -14,31 +14,18 @@ leaning on `Enumerable` and `Comparable` instead of hand-rolled loops, with
 `frozen_string_literal` hygiene and a real `Gemfile`/`.gemspec` when you package.
 
 This is **Ruby the language and its non-Rails ecosystem** — blocks, modules, gems,
-metaprogramming, Minitest/RSpec. The moment code loads the Rails framework or reaches
-for ActiveRecord/ActiveSupport idioms, it is no longer this skill — that is `rails`.
+metaprogramming, Minitest/RSpec. Delegate: Rails apps, ActiveRecord models, controllers,
+migrations, views, Hotwire — anything that loads Rails or uses ActiveSupport/ActiveRecord
+idioms — to [`rails`](../rails/SKILL.md); the same task in another language to
+[`python`](../python/SKILL.md), [`go`](../go/SKILL.md), [`rust`](../rust/SKILL.md),
+[`elixir`](../elixir/SKILL.md), [`php`](../php/SKILL.md) or
+[`typescript`](../typescript/SKILL.md); the CI pipeline that runs your Ruby tests to
+[`github-actions`](../github-actions/SKILL.md) — this skill writes the tests, not the workflow.
 
 Targets **Ruby 4.0** (released 2025-12-25) on **3.4** semantics: Prism is the default
 parser, string literals warn on mutation without a magic comment, `it` is an implicit
 block param, and `Set` is now a core class.
 
-## When to use / When NOT to use
-
-**Use when:**
-
-- Authoring or refactoring any plain-Ruby `.rb` file, CLI, script, gem, or library.
-- Turning imperative loops into `Enumerable` chains (`map`/`select`/`reduce`/`each_with_object`/`group_by`).
-- Designing module mixins, `Comparable`/`Enumerable` inclusion, refinements, or value objects (`Struct`/`Data`).
-- Setting up a gem: `bundle gem`, `.gemspec`, SemVer, version constraints, publishing to RubyGems.
-- Deciding whether metaprogramming (`method_missing`, `define_method`, `instance_eval`, DSLs) earns its keep.
-- Writing tests with Minitest or RSpec, wiring RuboCop/Standard, or adding RBS/Sorbet typing.
-
-**When NOT to use (delegate):**
-
-- Rails apps, ActiveRecord models, controllers, migrations, views, Hotwire -> `rails`.
-  The hard line: anything that loads Rails or uses ActiveSupport/ActiveRecord idioms.
-- The same task in another language -> `python`, `go`, `rust`, `elixir`, `php`, `typescript`.
-- A CI pipeline that runs your Ruby tests -> `github-actions` (this skill writes the tests, not the workflow).
-
 ## Mental model
 
 Internalize these before writing a line:
@@ -291,7 +278,8 @@ examples with `let`/`subject`/`context` are in
 - **Types:** two coexisting systems — **RBS** (official signatures in separate `.rbs`
   files, checked by Steep) and **Sorbet** (inline `sig` blocks, with experimental
   inline-RBS-comment support). Add types only on a library's public surface or a hot,
-  bug-prone core — not on throwaway scripts.
+  bug-prone core — not on throwaway scripts. RuboCop vs Standard config sits in
+  [references/gems-and-testing.md](references/gems-and-testing.md).
 
 ## Anti-patterns
 
@@ -305,12 +293,3 @@ examples with `let`/`subject`/`context` are in
 | Not committing `Gemfile.lock` for an app | Non-reproducible installs across machines | Commit it for apps; omit only for library gems |
 | `eval` of user-derived input | Remote code execution | Parse explicitly; never `eval` untrusted data |
 | Over-DSLing config a Hash would serve | Hidden control flow, slow `method_missing` | A plain Hash or `Data` object |
-
-## References
-
-- [references/metaprogramming.md](references/metaprogramming.md) — `define_method`,
-  `method_missing` + `respond_to_missing?`, `instance_eval`/`class_eval`, building a DSL,
-  refinements vs monkey-patching, `prepend` wrapping.
-- [references/gems-and-testing.md](references/gems-and-testing.md) — full `bundle gem`
-  tree and `.gemspec`, SemVer + `~>`, publishing, Rakefile, full Minitest + RSpec files,
-  RuboCop vs Standard config.

package/skills/shortform-ideation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: shortform-ideation
-description: "Use when an account that already posts (or is about to start posting) Reels/TikTok/Shorts needs a ranked batch of next video ideas grounded in its own performance log plus live trending sounds/formats/hashtags, and a ledger that ties each idea-bet to its measured outcome. Use to fold this week's trending audio into ideas, to decide which 3 of 12 ideas to shoot first, or to review why the bets you made flopped. Triggers: 'give me 10 Reels ideas for next week', 'which of these ideas do we make first', 'fold this week's trending TikTok sounds into our idea list', 'why did the ones we bet on last month flop', 'idea backlog for our TikTok', 'idéame Reels para esta semana basándote en lo que ya nos funcionó', 'prioritza idees de vídeo curt per aquesta setmana'. NOT writing the shot-by-shot script or edit decision sheet for a chosen idea (that is video-shorts), NOT setting cadence/pillars/positioning (that is shortform-strategy), NOT captions/covers/hashtag-sets for a finished cut (that is shortform-packaging)."
+description: "Use when a Reels/TikTok/Shorts account needs its next video ideas scored into a ranked backlog, grounded in its own performance log plus dated trending sounds, each bet logged so its outcome feeds the next batch. NOT scripting a chosen idea (that is `video-shorts`), NOT pillars or cadence (that is `shortform-strategy`), NOT packaging a finished cut (that is `shortform-packaging`)."
 tags: [shortform, reels, tiktok, ideation, content-ideas, trend-jacking, experiment-log]
 recommends: [video-shorts, shortform-strategy, shortform-packaging, analytics, content-engine]
 origin: risco
@@ -8,27 +8,27 @@ origin: risco
 
 # Shortform Ideation — The Idea Engine and the Bet Ledger
 
-*You run the closed loop for a Reels/TikTok/Shorts account: hypothesis → bet → measured outcome → a better next batch.* You own the idea list, the priority score, and the experiment ledger. You do not write the spoken lines, you do not pick the cadence, and you do not finalize the caption.
+*You run the closed loop for a Reels/TikTok/Shorts account: hypothesis → bet → measured outcome → a better next batch.* You own the idea list, the priority score, and the experiment ledger.
 
-**Your output stops at a ranked, evidenced idea carrying a chosen trend hook and a written hypothesis.** The moment you start writing spoken lines or beat timecodes, you have crossed into `video-shorts`. Hand off; do not squat.
+**Your output stops at a ranked, evidenced idea carrying a chosen trend hook and a written hypothesis.** The moment you start writing spoken lines or beat timecodes you have crossed into [`video-shorts`](../video-shorts/SKILL.md) — hand off, do not squat.
 
 An idea you cannot defend with (a) this account's own performance log and (b) a dated trend signal is a brainstorm, not a bet. This skill refuses to emit a brainstorm dump.
 
 ## Decision gate — are you even in ideation?
 
-Read the ask against this table before you generate anything. *Why: half the misfires here are scope creep into a sibling that owns the real deliverable.*
+Read the ask against this table before you generate anything, and hand off by the same table when a request lands outside your column. *Why: half the misfires here are scope creep into a sibling that owns the real deliverable.*
 
 | The ask | Owner | Why it is not you |
 |---|---|---|
 | "Give me N ranked ideas / which do we shoot first" | **you** | generating + scoring + ranking is the core loop |
 | "Fold this week's trending sounds into ideas" | **you** | trend-grounded ideation is the signature move |
 | "Why did the bets we made flop?" | **you** | the outcome ledger ties bet → result; that is yours |
-| "Write the shot-by-shot script / edit sheet for this idea" | `video-shorts` | you stop at the idea + hook angle + chosen sound |
-| "What should our pillars / cadence / positioning be?" | `shortform-strategy` | you consume pillars as input, you do not set them |
-| "Write the caption + hashtags + cover for this finished cut" | `shortform-packaging` | you may *suggest* a hashtag as a trend signal, not finalize one |
-| "YouTube ideas with thumbnail-first packaging" | `youtube-ideation` | that pipeline is packaging-led and decays slower |
-| "Run the cross-channel calendar across blog/email/social" | `content-engine` | you feed ranked ideas *into* a calendar, you don't run it |
-| "Build me a metrics dashboard" | `analytics` | you *read* the perf log to score ideas, you don't build reporting |
+| "Write the shot-by-shot script / edit sheet for this idea" | [`video-shorts`](../video-shorts/SKILL.md) | you stop at the idea + hook angle + chosen sound |
+| "What should our pillars / cadence / positioning be?" | [`shortform-strategy`](../shortform-strategy/SKILL.md) | you consume pillars as input, you do not set them |
+| "Write the caption + hashtags + cover for this finished cut" | [`shortform-packaging`](../shortform-packaging/SKILL.md) | you may *suggest* a hashtag as a trend signal, not finalize one |
+| "YouTube ideas with thumbnail-first packaging" | [`youtube-ideation`](../youtube-ideation/SKILL.md) | that pipeline is packaging-led and decays slower |
+| "Run the cross-channel calendar across blog/email/social" | [`content-engine`](../content-engine/SKILL.md) | you feed ranked ideas *into* a calendar, you don't run it |
+| "Build me a metrics dashboard" | [`analytics`](../analytics/SKILL.md) | you *read* the perf log to score ideas, you don't build reporting |
 
 ## The loop — four phases, in order
 
@@ -118,6 +118,8 @@ The hypothesis is one falsifiable sentence:
 
 Then leave the **result fields pending** — `result: pending | 3s-hold: __ | hook-rate: __ | shares: __ | saves: __ | verdict: __` — to be filled after the video runs. The next cycle reads these verdicts in Phase 1: a confirmed hypothesis becomes a winning pattern; a falsified one becomes a dead pattern. *Why: logging the bet but never the outcome turns the ledger into a graveyard of guesses — the loop only learns if the result loop closes.*
 
+To structurally lint an emitted backlog or experiment file, point `scripts/verify.sh` at it (read-only): `bash scripts/verify.sh 02-DOCS/shortform/`.
+
 ## Metrics that matter
 
 Score and judge on these, not on raw views. *Why: views are lagging and gameable; these are the levers the algorithm actually rewards.*
@@ -141,13 +143,3 @@ Score and judge on these, not on raw views. *Why: views are lagging and gameable
 | Logging the bet but never the outcome | the loop never learns; next batch re-guesses | leave result fields and fill them; Phase 1 reads the verdicts |
 | Writing the full script/timecodes here | crosses into `video-shorts`; muddies the idea ledger | stop at hook line + chosen sound; hand off |
 | Capturing a trend signal with no date | freshness is unscorable; you may brief a dead sound | every signal carries a first-seen date or it doesn't enter Phase 3 |
-
-## Hand-off
-
-- Chosen an idea and need the shot-by-shot script + edit decision sheet? → [`../video-shorts/SKILL.md`](../video-shorts/SKILL.md).
-- Missing the pillars/cadence/positioning the ideas should fit inside? → `shortform-strategy` (it owns strategy; you consume it).
-- The cut exists and needs caption/cover/hashtag-set? → `shortform-packaging`.
-- Feeding the ranked backlog into a multi-channel calendar? → [`../content-engine/SKILL.md`](../content-engine/SKILL.md).
-- Long-form/YouTube idea pipeline instead? → [`../youtube-ideation/SKILL.md`](../youtube-ideation/SKILL.md).
-
-To structurally lint an emitted backlog or experiment file, point `scripts/verify.sh` at it (read-only): `bash scripts/verify.sh 02-DOCS/shortform/`.