@ericrisco/rsc 0.1.43 → 0.1.45

package/skills/tasks/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tasks
-description: "Use when you have an approved implementation plan and need to break it into an ordered, independently-verifiable task list before any code is written — the SDD `tasks` phase (GitHub Spec Kit lineage: constitution → specify → clarify → plan → tasks → analyze → implement). Turns a plan into numbered tasks, each with an explicit done-check (the literal command or observation that proves it complete), dependencies, and a parallel-safe marker. Triggers: 'break the plan into tasks', 'make a task list', 'task breakdown', 'descompón el plan en tareas', 'lista de tareas', 'what are the steps to build this', 'turn the plan into a checklist', 'sequence the work', 'which tasks can run in parallel', 'give each task a done-check'. Appends the task list into the plan artifact under 02-DOCS/wiki/sdd/plans/<slug>.md. NOT writing the plan itself (that is `plan`), NOT the consistency gate over the artifacts (that is `analyze`), NOT executing the tasks (that is `implement`)."
+description: "Use when an approved plan needs slicing into an ordered task list before any code — the SDD `tasks` phase. Each row carries a literal done-check, dependencies, a parallel-safe marker and a spec trace, appended to the plan artifact. NOT writing the plan (that is `plan`), NOT the consistency gate (that is `analyze`), NOT executing the tasks (that is `implement`)."
 tags: [sdd, tasks, breakdown]
 recommends: [analyze, implement]
 profiles: [core, full]
@@ -20,29 +20,25 @@ task list says "T004: implement `POST /login`; done when `pytest
 tests/auth/test_login.py` is green AND a 401 is returned for a bad password —
 depends on T002, T003; parallel-safe with T005." The difference is that the
 second one can be **handed to a subagent, executed, and verified** with no
-further questions.
-
-This is a process skill. It writes no runtime code. It produces one artifact: an
-ordered, checkable task list appended to the plan it was built from.
+further questions. This phase writes zero runtime code; it produces one artifact,
+appended to the plan it was built from.
 
 ## Model tier — `balanced` (opt-in routing)
 
-This phase's default model tier is **`balanced`** — it decomposes an approved plan into verifiable tasks: structured work, not architecture. 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.
+This phase's default tier is **`balanced`**: decomposing an approved plan is
+structured work, not architecture. Routing is off unless `models.enabled: true`
+in `02-DOCS/wiki/sdd/config.yaml`; when on, resolve the tier and apply it per
+`../sdd/references/model-routing.md`, which owns the resolution order and the
+announcement rules. Routing off or no profile → honor the session model silently.
 
 ## Read the harness profile first
 
-Before producing anything, read `02-DOCS/wiki/harness/user-profile.md` for the
-technical level and the **accompaniment dial**, and adapt:
-
-- **L0 (cavernícola)** — emit the task table, nothing else. No commentary.
-- **L1 (breve)** — one line of *why this slicing* above the table.
-- **L2 (explica decisiones)** — justify the ordering and the parallel markers as
-  you go; flag the risky tasks.
-- **L3 (acompañamiento total)** — explain the slicing method, walk each
-  dependency, and confirm the done-checks make sense to the user before writing.
-
-If no profile exists, assume non-technical + ask the two gauging questions the
-harness defines before slicing. Never invent a level.
+Read `02-DOCS/wiki/harness/user-profile.md` before producing anything and match
+the accompaniment dial: **L0** emit the task table and nothing else; **L1** add
+one line of *why this slicing* above it; **L2** justify the ordering and the
+parallel markers as you go, flagging the risky tasks; **L3** walk each dependency
+and confirm the done-checks make sense to the user before writing. No profile →
+assume non-technical and let `init` gauge the level; never invent one.
 
 ## Inputs (refuse to start without them)
 
@@ -154,10 +150,10 @@ The task list is **not** a new document. Append it to the existing plan under a
 ```
 
 Then ensure the plan is indexed in `02-DOCS/wiki/index.md` (the Knowledge map;
-root `CLAUDE.md` keeps only a short pointer) under
-the `sdd/` topic (the `plan` phase usually added the row; confirm it points at
-`02-DOCS/wiki/sdd/plans/<slug>.md`, add it if missing — additive only, never
-delete a user's map entry).
+root `CLAUDE.md` keeps only a short pointer) under the `sdd/` topic — the `plan`
+phase usually added the row, so confirm it points at
+`02-DOCS/wiki/sdd/plans/<slug>.md` and add it if missing. Additive only: never
+delete a user's map entry.
 
 ### The table format
 
@@ -181,8 +177,8 @@ delete a user's map entry).
 subagent) that see *only their own task* — not the whole plan. Such a worker can't infer a
 neighbor's function signature, payload shape, or column name from a one-line row. For any task
 whose correctness depends on a contract it doesn't own, attach an **Interfaces block** right under
-its row. (Trivial, self-contained tasks don't need one — don't add ceremony where there's no
-cross-task contract.)
+its row. Trivial, self-contained tasks don't need one — don't add ceremony where there's no
+cross-task contract.
 
 ```markdown
 **T004 — Interfaces**
@@ -190,15 +186,13 @@ cross-task contract.)
 - Produces: `POST /login` → `200 {token}` | `401 {error}`; sets `Set-Cookie: sid=…; HttpOnly`
 ```
 
-Rules:
-
-- Quote **exact** signatures/shapes, not descriptions — the isolated worker copies them, it can't
-  go look them up. "Returns the user" is invisible; `-> {id, email}` is usable.
-- `Consumes` names what the task reads from a neighbor or the environment; `Produces` names the
-  contract later tasks (and the per-task reviewer) will hold it to.
-- The plan's **§0 Global Constraints** are inherited by every task implicitly — do **not** repeat
-  them per task. Interfaces carry the *task-local* contract; Global Constraints carry the
-  *project-wide* one. Together they are everything a blind implementer needs.
+Quote **exact** signatures and shapes, not descriptions — the isolated worker copies them, it can't
+go look them up. "Returns the user" is invisible; `-> {id, email}` is usable. `Consumes` names what
+the task reads from a neighbor or the environment; `Produces` names the contract later tasks (and
+the per-task reviewer) will hold it to. The plan's **§0 Global Constraints** are inherited by every
+task implicitly — do **not** repeat them per task. Interfaces carry the *task-local* contract;
+Global Constraints carry the *project-wide* one. Together they are everything a blind implementer
+needs.
 
 ## Review workload + delivery strategy forecast
 
@@ -216,12 +210,11 @@ before a giant diff exists.
 | Suggested delivery | single-pr / ask-on-risk / autochain / exception | matched to config.review_budget |
 ```
 
-Rules:
-
-- If estimated changed lines exceed `config.sdd.review_budget.line_budget` (default 400), recommend splitting or `ask-on-risk`.
-- If many areas or cross-stack contracts are touched, recommend `autochain` or a feature-track branch.
-- If the change is tiny, recommend `single-pr`.
-- If a deadline or emergency justifies a large review, mark `exception` and require explicit user approval later.
+Pick the delivery strategy from the forecast: tiny change → `single-pr`; estimated
+lines over `config.sdd.review_budget.line_budget` (default 400) → recommend
+splitting or `ask-on-risk`; many areas or cross-stack contracts touched →
+`autochain` or a feature-track branch. A deadline or emergency that justifies a
+large review is marked `exception` and requires explicit user approval later.
 
 ## Anti-patterns → STOP
 
@@ -236,19 +229,6 @@ Rules:
 | "I'll start coding the easy task while I list the rest" | This phase writes zero runtime code. Implementation is `implement`. |
 | "Renumber the IDs so they're contiguous" | Downstream phases cite IDs. They're stable once written. Append, don't renumber. |
 
-## Done-of-done for this phase
-
-Before handing off, confirm:
-
-- [ ] Every plan deliverable maps to at least one task.
-- [ ] Every task has a runnable done-check (a command or a checkable observation).
-- [ ] Every task traces to a spec line; no orphan tasks.
-- [ ] Dependencies form a valid order (nothing precedes what it needs).
-- [ ] `[P]` markers only on file/state-disjoint tasks.
-- [ ] The list is appended under `## Tasks` in the plan artifact, indexed in the Knowledge map at `02-DOCS/wiki/index.md` (root `CLAUDE.md` keeps only a short pointer).
-- [ ] A final closer task gates on all done-checks + `verify.sh`.
-- [ ] Review workload forecast and suggested delivery strategy appended.
-
 ## Result envelope
 
 End with:
@@ -272,14 +252,11 @@ End with:
 
 ## Next in the SDD chain
 
-The task list is now the contract for the rest of the build. Hand off:
-
-- **→ `analyze`** — the consistency gate. Before any code, cross-check
-  constitution ↔ spec ↔ plan ↔ **tasks** for gaps, contradictions, and scope
-  drift. Orphan tasks and untraceable scope surface here. Report only; the user
-  resolves.
-- then **→ `implement`** — execute the tasks in order, TDD-style (red → green →
-  refactor), using `parallel` for the `[P]` tasks and `worktrees` for isolation.
+The task list is now the contract for the rest of the build. Hand off to
+**`analyze`** — the consistency gate that cross-checks constitution ↔ spec ↔ plan
+↔ **tasks** and surfaces orphan tasks and untraceable scope — and then to
+**`implement`**, which executes the list TDD-style, using `parallel` for the `[P]`
+tasks and `worktrees` for isolation.
 
 Do not jump straight to `implement`. The whole point of writing a checkable list
 was to let `analyze` audit it cheaply *before* code exists.
@@ -287,4 +264,3 @@ was to let `analyze` audit it cheaply *before* code exists.
 ## Orientación (siempre)
 
 Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ✅ qué hiciste · 🧭 por qué · ➡️ siguiente, terminando en pregunta), calibrado al dial de `02-DOCS/wiki/harness/user-profile.md`. **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)
-

package/skills/typescript/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: typescript
-description: "Use when writing, reviewing, or fixing TypeScript type code (.ts/.tsx/.d.ts), modeling data with generics/unions/branded types, or configuring tsconfig and the build toolchain - the language and type system itself, not any runtime or framework. Triggers: \"make this generic preserve the literal type\", \"why won't this narrow / why won't TypeScript narrow this union\", \"type X is not assignable to type Y, fix the type not cast it\", \"set up a strict tsconfig with project references\", \"convert these magic strings into a discriminated union with exhaustiveness\", \"bundler vs nodenext moduleResolution\", \"configura el tsconfig en modo estricto y elimina los any\", \"por qué no estrecha el tipo\". NOT the Node runtime, fs/streams/http server (that is nodejs); NOT React/Next component wiring (that is react/nextjs); NOT ORM schema type-gen (that is drizzle-orm)."
+description: "Use when writing or fixing TypeScript type code (.ts/.tsx/.d.ts), modeling data with generics/unions/branded types, diagnosing narrowing failures, or configuring tsconfig and the build toolchain. NOT runtime code, fs/streams/http (that is `nodejs`); NOT component/route typing (that is `react`/`nextjs`); NOT ORM type-gen (that is `drizzle-orm`)."
 tags: [typescript, types, generics, tsconfig, type-safety]
 recommends: [nodejs, secure-coding, drizzle-orm]
 origin: risco
@@ -18,42 +18,18 @@ compiler** (`tsgo`, the Go port) is in preview as `@typescript/native-preview` a
 type-checks roughly 10x faster (VS Code's 1.5M LOC: 89s -> 8.74s) — adopt it for fast
 local checks; stable 7.0 lands early 2026.
 
-This is a *language* skill: the type system plus the compiler config. It is the canonical
-authority for "how do I express this in TS and make `tsc` honor it", independent of any
-runtime or framework.
-
-## When to use / When NOT to use
-
-**Use when:**
-
-- Authoring or fixing type code: generics, constraints, overloads, conditional/mapped/
-  template-literal types, utility types, narrowing, `.d.ts` declarations.
-- Modeling data: discriminated unions, `satisfies`, branded/nominal types, exhaustiveness.
-- Setting up or hardening `tsconfig.json`: strict flags, `moduleResolution`, project
-  references, path aliases, declaration emit, `isolatedModules`/`verbatimModuleSyntax`.
-- Diagnosing type errors: "why won't this narrow", "X is not assignable to Y", inference
-  failures, `any`/`unknown` leakage, variance surprises.
-- Choosing the build toolchain: `tsc` vs `tsgo` (TS7), `tsx`, bundler vs nodenext resolution.
-
-**When NOT to use (delegate):**
-
-- Node runtime/server code — event loop, `fs`, streams, `http` server, `process`, env -> `nodejs`.
-- React/Next/Nest component or framework typing *in framework context* -> `react` / `nextjs` /
-  `nestjs` (the type-level mechanics still come from here; the framework wiring does not).
-- ORM schema-to-type generation (Drizzle/Prisma) -> `drizzle-orm` / `prisma-orm`.
-- REST/contract shape design (status codes, resource naming) -> `api-design`.
-- Test runner / coverage / E2E setup -> `testing-web` / `e2e-testing`.
-- Language-agnostic injection/authz/threat review -> `secure-coding`.
-- Python typing -> `python`; Go -> `go`.
-
 ## Boundary: language vs runtime vs framework
 
-Three layers, three owners. **Language + compiler config lives here** (`tsconfig`, generics,
-narrowing). **Runtime behavior** (how a stream backpressures, how the event loop schedules)
-is `nodejs`. **Framework idioms** (component props, route maps, server-component typing) are
+Three layers, three owners. **Language + compiler config lives here** — generics, narrowing,
+`.d.ts`, `tsconfig`, and the build toolchain (`tsc` vs `tsgo`, `tsx`, resolution mode).
+**Runtime behavior** (how a stream backpressures, how the event loop schedules) is `nodejs`.
+**Framework idioms** (component props, route maps, server-component typing) are
 `react`/`nextjs`/`nestjs` — those *borrow* this skill's type mechanics but own their wiring.
 A `tsconfig` question is here; a "stream backpressure" question is `nodejs`; a "type my
-`useReducer` state" question is `react`.
+`useReducer` state" question is `react`. Also delegate: ORM schema-to-type generation ->
+`drizzle-orm` / `prisma-orm`; REST/contract shape design -> `api-design`; test runner and E2E
+setup -> `testing-web` / `e2e-testing`; injection/authz review -> `secure-coding`; Python
+typing -> `python`; Go -> `go`.
 
 ## Decision rules
 
@@ -62,28 +38,13 @@ Apply these on every TypeScript edit:
 1. **Prefer inference; annotate boundaries.** Let TS infer locals and returns; annotate
    function parameters, public APIs, and `.d.ts`. Why: redundant annotations drift from
    reality and suppress the better inferred type.
-2. **`unknown`, never `any`.** `any` disables checking and leaks; `unknown` forces a narrow
-   before use. Why: `any` silently poisons every downstream type it touches.
-3. **`import type` for type-only imports**, with `verbatimModuleSyntax: true`. Why: it
+2. **`import type` for type-only imports**, with `verbatimModuleSyntax: true`. Why: it
    prevents emitting type-only imports as runtime `require`s and lets esbuild/swc transpile
    each file alone.
-4. **Model state as discriminated unions, not optional-field bags.** A literal discriminant
-   makes illegal states unrepresentable. Why: `{ data?: T; error?: E; loading?: bool }`
-   permits `loading && error` — a union does not.
-5. **`satisfies` for config objects, not a type annotation.** Why: annotation widens the
-   value to the type (you lose literal keys); `satisfies` validates *without* widening, and
-   catches discriminant typos at the construction site.
-6. **Narrow, don't cast.** Reach for type guards, `in`, `typeof`, discriminant checks before
-   `as`. Why: `as` asserts a claim the compiler cannot verify — it is a silenced error.
-7. **`as` is a last resort, and only `as <narrower>` or `as unknown as T` at true I/O
-   boundaries.** Why: `as` to a *wider* or unrelated type is almost always a real bug hidden.
-8. **One `tsconfig` base, extended per package.** A shared `tsconfig.base.json` holds strict
-   flags; each package `extends` it and sets only `outDir`/`rootDir`/references. Why: a single
-   giant config can't express per-package module targets and breaks project references.
-9. **Turn on `noUncheckedIndexedAccess`.** Why: `arr[i]` and `record[key]` are `T | undefined`
-   in reality — without this flag TS lies and you get runtime `undefined`.
-10. **Make unions exhaustive with a `never` guard.** A `default: const _: never = x` in
-    every switch over a union turns "added a case, forgot a branch" into a compile error.
+3. **Narrow, don't cast.** Reach for type guards, `in`, `typeof`, discriminant checks before
+   `as`; when `as` is unavoidable, only `as <narrower>` or `as unknown as T` at a true I/O
+   boundary. Why: `as` asserts a claim the compiler cannot verify — it is a silenced error,
+   and `as` to a *wider* or unrelated type is almost always a real bug hidden.
 
 ## The type-system toolbox
 
@@ -105,6 +66,9 @@ const r = pick({ a: 1, b: "x" } as const, "b"); // r: "x", not string
 
 ### `unknown` over `any` at every boundary
 
+`any` disables checking and silently poisons every downstream type it touches; `unknown`
+forces a narrow before use.
+
 ```ts
 // Bad: any flows everywhere, no error ever fires downstream.
 function parse(json: string): any { return JSON.parse(json); }
@@ -133,8 +97,11 @@ routes.home.method; // "GET" (narrow), and "GE" would error right here
 
 ### Discriminated unions + exhaustive `never`
 
-The discriminant must be a **literal** type (not `string`), and you must check it **before**
-destructuring — destructuring first throws away the narrowing.
+Model state as a discriminated union, not an optional-field bag:
+`{ data?: T; error?: E; loading?: boolean }` permits `loading && error`; a literal discriminant
+makes illegal states unrepresentable. That discriminant must be a **literal** type (not
+`string`), and you must check it **before** destructuring — destructuring first throws away
+the narrowing.
 
 ```ts
 type State =

package/skills/verify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: verify
-description: "Use when implementation is finished and someone is about to say it's done, shipped, working, or ready to merge in the rsc-sdd flow — the post-implementation GATE that demands evidence before any 'done' claim. Triggers: 'verify this feature', 'is it done?', 'run the checks', 'lint/type/test before merge', 'did the acceptance criteria pass', 'confirm the tasks are complete', 'gate before review', 'audit the change', 'are we green', 'prove it works'. Runs the relevant stack skill's scripts/verify.sh (lint, type-check, tests, coverage, dependency/vuln audit), then walks every task done-check and every spec acceptance criterion, attaching the actual command output as evidence. Writes the verification record under 02-DOCS/wiki/sdd/ and points to the review phase. NOT writing tests or features (that is implement), NOT adversarial code reading (that is review), NOT root-cause diagnosis of a failing test (that is debug). Honors the harness accompaniment dial."
+description: "Use when implementation is finished and about to be called done or merged — the rsc-sdd evidence gate: runs the stack's scripts/verify.sh (lint, type, test, audit), walks every task done-check and acceptance criterion, records a dated verdict. NOT judging the diff by eye (that is `review`, spec-less `code-review`), NOT diagnosis (that is `debug`)."
 tags: [sdd, verify, test]
 recommends: [review]
 profiles: [core, full]
@@ -15,21 +15,7 @@ The one rule everything else serves: **a claim of done is a claim about evidence
 
 This is a process skill. It does not own the lint/type/test tooling — the **stack skills do** (`../fastapi/SKILL.md`, `../go/SKILL.md`, `../nextjs/SKILL.md`, `../flutter/SKILL.md`, each shipping `scripts/verify.sh`; data-layer checks come from `../postgresdb/SKILL.md`, security from `../secure-coding/SKILL.md`). `verify` orchestrates them and judges the whole against the spec.
 
-## When to use / when not to
-
-Use when:
-
-- Implementation of a task or feature is complete and you (or the user) are about to say so.
-- A fix has been applied and you need to confirm it actually resolves the issue, with the app's own checks.
-- You're at the gate before the `review` phase, or before a merge / PR.
-- Someone asks "is it done?", "are we green?", "did it pass?", "can I merge?".
-
-Do NOT use when:
-
-- You're still writing tests or production code → that's the `implement` phase (TDD lives there).
-- A check is failing and you need to find out *why* → that's `debug` (reproduce → isolate → fix). `verify` reports the failure and hands off; it does not diagnose.
-- You're reading the diff adversarially for design/correctness smells a test can't catch → that's `review`.
-- There is no spec or task list to verify against → you're earlier in the chain; go to `specify`/`plan`/`tasks` first.
+Not this phase: still writing tests or production code → `../implement/SKILL.md` (TDD lives there); a check is failing and you need to know *why* → `../debug/SKILL.md` (`verify` reports the failure and hands off, it does not diagnose); reading the diff adversarially for design/correctness smells a test can't catch → `../review/SKILL.md`, or `../code-review/SKILL.md` when there is no spec/plan chain to key off; nothing to verify *against* → you're earlier in the chain, go to `../specify/SKILL.md` / `../plan/SKILL.md` / `../tasks/SKILL.md` first.
 
 ## Model tier — `balanced` (opt-in routing)
 
@@ -37,15 +23,13 @@ This phase's default model tier is **`balanced`** — it runs the checks and int
 
 ## Read the room first (accompaniment dial)
 
-Before running anything, read `02-DOCS/wiki/harness/user-profile.md` for the technical + accompaniment level and adapt:
+Before running anything, read `02-DOCS/wiki/harness/user-profile.md` for the technical + accompaniment level; no profile yet → default to non-technical framing. The verdict itself (pass / fail per item) never changes with the dial — only how much you explain around it.
 
 - **L0** — run the gate, show pass/fail and the one-line failing summary. Minimal words.
 - **L1** — add one line of *why* per failing check.
 - **L2** — narrate each gate (what lint/type/test/audit checks and why it matters here).
 - **L3** — explain every result, what each acceptance criterion means in plain language, and what the user should decide next.
 
-If no profile exists yet, default to non-technical framing and keep the verdict legible. The verdict itself (pass / fail per item) never changes with the dial — only how much you explain around it.
-
 ## The gate (run in this order)
 
 ```text
@@ -105,12 +89,10 @@ Rules for RUN:
 The stack gate proves the code is *clean and tested*. It does **not** prove the feature does what the spec asked. Walk both lists explicitly:
 
 - **Task done-checks** — for each task in the plan, confirm its done-check is satisfiable from evidence (a passing test, a file that exists, an endpoint that returns the documented shape). Mark each ✅ with the evidence or ❌ with what's missing.
-- **Acceptance criteria** — for each criterion in the spec, point at the concrete evidence that satisfies it. A criterion with no test and no observable proof is **unverified** — treat it as a FAIL item, not a pass, until there is evidence.
+- **Acceptance criteria** — for each criterion in the spec, point at the concrete evidence that satisfies it. A criterion with no test and no observable proof is **unverified** — treat it as a FAIL item, not a pass, until there is evidence. A criterion you "reviewed by reading the code" is not verified either: reading is `review`; verifying needs an observable result.
 
 Where a criterion needs runtime proof (a page renders, a command produces output), drive it through the relevant tool — defer browser/app runtime to the stack skill's own runtime guidance rather than inventing a check here.
 
-A criterion you "reviewed by reading the code" is not verified. Reading is `review`; verifying needs an observable result.
-
 ### 4 — RECORD
 
 Write a dated verification record to `02-DOCS/wiki/sdd/verifications/<slug>-YYYY-MM-DD.md` so the project's living knowledge carries the proof, then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer) under the `sdd/` topic. It is an OKF v0.1 wiki article: open it with YAML frontmatter carrying a non-empty `type:`. Keep it short and factual:
@@ -151,9 +133,9 @@ Append-only spirit: don't overwrite a prior run's record; a new run is a new dat
 - **FAIL** the moment any item lacks passing evidence. List the open items precisely (which check, which criterion, what's missing). Do not soften it. A single unverified acceptance criterion fails the whole gate.
 - Hand each failing kind to the right place: a failing test/type error → `debug`; a missing test for a criterion → back to `implement`; a spec ambiguity that surfaced → `clarify`.
 
-## Anti-patterns → STOP
+## Anti-patterns
 
-| Rationalization | Reality |
+| Anti-pattern | Why it fails / fix |
 | --- | --- |
 | "The tests passed last run, I'll trust that." | Re-run now. Code changed since; stale green is not green. Evidence is current, or it isn't evidence. |
 | "verify.sh printed SKIP for the tests — close enough." | A SKIP is *unverified*, not passing. The criterion it covers is still open until a real run passes. |
@@ -163,13 +145,7 @@ Append-only spirit: don't overwrite a prior run's record; a new run is a new dat
 | "One acceptance criterion is unproven; ship the rest." | The gate is all-or-nothing. One unverified criterion fails the whole verdict. |
 | "A test is failing — let me just fix it real quick." | That's `debug`, a different discipline. `verify` reports the failure and hands off; it does not patch mid-gate. |
 | "I'll write the verdict, then run the checks to confirm." | Backwards. RUN and WALK first; the verdict is the *consequence* of output you already read. |
-
-## Red flags — abort the verdict
-
-- You're about to type "done"/"passing"/"works" and you cannot point to a specific line of command output that proves it. Stop; go run it.
-- The stack `verify.sh` for a touched stack doesn't exist or didn't run — the gate is incomplete; say so instead of declaring PASS.
-- An acceptance criterion has no test and no observable proof — it's unverified; the verdict is FAIL.
-- A failing check tempts you to fix it inline — that's scope drift into `debug`; record the failure and hand off.
+| "The gate is mostly green, I'll call it done." | If you cannot point at the line of command output that proves a claim, you have no claim. Go run it. |
 
 ## Result envelope
 
@@ -194,7 +170,7 @@ End with:
 
 ## Next in the chain
 
-A **PASS** record is the entry ticket to the next phase: **`review`** (adversarial read of the diff for what the gate can't catch), then **`ship`** (PR/merge with Eric-only authorship). A **FAIL** routes back: failing checks to **`debug`**, missing coverage to **`implement`**, surfaced ambiguity to **`clarify`**. Either way the verification record under `02-DOCS/wiki/sdd/verifications/` travels with the work as its proof.
+A **PASS** record is the entry ticket to the next phase: **`../review/SKILL.md`** (adversarial read of the diff for what the gate can't catch), then **`../ship/SKILL.md`** (PR/merge). A **FAIL** routes back per the VERDICT step. Either way the verification record under `02-DOCS/wiki/sdd/verifications/` travels with the work as its proof.
 
 ## Orientación (siempre)
 

package/skills/viral-score/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: viral-score
+description: "Use to judge whether a short-form clip is worth publishing — scores a reel, short or podcast excerpt 0-100 on ten weighted criteria with automatic penalties, then ranks a batch and says where the cut-off falls. Run it on transcript candidates before rendering. NOT writing the hook or caption (that is `shortform-packaging`), NOT inventing the idea (that is `shortform-ideation`), NOT executing the edit (that is `shortform-editing`)."
+tags: [viral, score, rubric, shortform, reels, shorts, tiktok, ranking, evaluation, retention]
+recommends: [shortform-packaging, shortform-ideation, shortform-editing, shortform-strategy, video-shorts]
+profiles: []
+origin: risco
+---
+
+# viral-score — is this clip worth publishing?
+
+A fixed rubric for scoring a vertical clip's chance of travelling. Its value is that it is
+**fixed**: the same clip scores the same on Monday and Friday, and two clips are comparable
+because they were measured with the same instrument.
+
+So **do not substitute your own judgment for the rubric and do not adjust the weights.** If a clip
+has a quality the rubric does not capture, say so in the reasons — but score it with this.
+
+Score candidates **before rendering** whenever you can. Judging a transcript excerpt costs seconds;
+editing a clip that gets discarded costs an afternoon.
+
+## The ten criteria
+
+Each is scored **0-10**.
+
+| # | Criterion | Weight | What earns the points |
+|---|---|---|---|
+| 1 | **Opening hook** | 20 % | Do the first 3 seconds stop the scroll? Curiosity, surprise, emotion, a strong claim, a striking open |
+| 2 | **Expected retention** | 20 % | Is there a reason to reach the end? Sustained curiosity, pace, resolution, no dead air |
+| 3 | **Emotional impact** | 15 % | Intensity: inspiration, awe, fear, anger, joy, nostalgia, humour, surprise. **Indifference scores very low** |
+| 4 | **Shareability** | 10 % | Would someone send this to a friend? |
+| 5 | **Comment-worthiness** | 10 % | Does it invite debate or a reply? |
+| 6 | **Message clarity** | 5 % | Does the idea fit in one sentence? |
+| 7 | **Value density** | 5 % | Does every second earn its place? |
+| 8 | **Originality** | 5 % | Is it different or unexpected? |
+| 9 | **Context independence** | 5 % | Does it land without having heard the rest of the episode? |
+| 10 | **Storytelling** | 5 % | Is there a story, a lesson, or a transformation? |
+
+## The calculation
+
+```text
+Viral Score = ( Hook×0.20 + Retention×0.20 + Emotion×0.15 + Shareability×0.10
+              + Comments×0.10 + Clarity×0.05 + Density×0.05
+              + Originality×0.05 + Context×0.05 + Storytelling×0.05 ) × 10
+```
+
+## Automatic penalties
+
+Subtracted **after** the formula, and they stack.
+
+| Penalty | Points |
+|---|---|
+| Weak hook | −10 |
+| Slow intro | −8 |
+| Needs too much context | −10 |
+| Long pauses | −5 |
+| Idea too generic | −8 |
+| Provokes no emotion | −10 |
+| Unsatisfying ending | −5 |
+
+Clamp the final result to **[0, 100]**.
+
+## Reading the score
+
+| Range | Verdict |
+|---|---|
+| 95-100 | Exceptional. Publish immediately |
+| 90-94 | Very likely to perform |
+| 80-89 | Good candidate. Worth editing and publishing |
+| 70-79 | Acceptable, but there are better clips |
+| 60-69 | Weak. Publish only if there is no alternative |
+| 0-59 | Discard |
+
+## Required output, per clip
+
+- **Start** and **end timestamp**
+- **Viral Score** (0-100)
+- A **table** with all ten criterion scores
+- **Reasons** behind the scoring
+- **Main strengths**
+- **Main weaknesses**
+- **Verdict**: Publish / Review / Discard
+
+Scoring several clips adds two things: a **ranking from highest to lowest**, and **where the
+cut-off falls** — the point below which publishing stops being worth it.
+
+## Applying it well
+
+**Score the clip, not the topic.** A fascinating episode routinely yields a clip that scores 45.
+
+**Judge the hook on the actual first three seconds**, not on the idea in the abstract. A clip that
+opens with a filler word or halfway through a sentence has a weak hook: −10. That is also why the
+excerpt should start on a sentence boundary — where you cut decides the hook.
+
+**Be strict about context independence.** If the viewer needs to know who the guest is, or what the
+previous question was, that is −10.
+
+**Do not inflate the mean.** If twenty clips all come out above 80, the rubric is not being applied.
+A healthy batch spreads widely, with few above 85.
+
+**Justify every low score with what happens in the clip**, at a timestamp — not with a generality.
+
+## Anti-patterns
+
+| Anti-pattern | Do instead |
+|---|---|
+| Scoring how interesting the subject is | Score this clip's execution; the topic is not the artifact |
+| Grading the hook from the full idea | Read only the first three seconds as the viewer receives them |
+| Compressing a batch into 78-85 | Use the range; a flat distribution means the instrument is not being used |
+| "Weak hook" with no evidence | Quote the opening words and the timestamp |
+| Adjusting weights for a clip you like | The weights are the instrument. Argue in the reasons, score with the rubric |
+| Rendering first, scoring after | Score transcript candidates, then edit only what survives |
+| Skipping the penalties because the total looks low | They are automatic and they stack; a 72 with three penalties is a 49 |
+
+## See Also
+
+- `../shortform-packaging/SKILL.md` — the hook line, caption, hashtags and cover for a clip that
+  passed this bar.
+- `../shortform-ideation/SKILL.md` — inventing the angle, upstream of anything scoreable.
+- `../shortform-editing/SKILL.md` — executing the edit once a clip is chosen.
+- `../shortform-strategy/SKILL.md` — what the channel should publish over time, which this feeds
+  with per-clip evidence.

package/skills/viral-score/evals/README.md

@@ -0,0 +1,16 @@
+# Evals — viral-score
+
+These are routing and capability checks, not an automated harness. Run them by hand:
+read each `should_trigger` prompt and confirm the skill fires on it — including the two
+non-obvious ones ("this clip feels flat but I can't say why" and the retrospective "why
+did this short underperform"), which carry no scoring keyword, and the Spanish prompt;
+read each `should_not_trigger` prompt and confirm the description's NOT-boundary sends it
+to the named `route_to` sibling instead. The neighbours are close together, so the
+packaging / ideation / editing / strategy split is the part most worth checking.
+
+For the `capability` cases, score the described clip for real and check the answer hits
+every `must_include` line. The first case exists because penalties are the step most often
+skipped: an opener mid-sentence, a 4s pause and an unresolved ending must each subtract,
+and the total must be clamped after they do. The second checks that batch mode produces
+what a single-clip run does not — a ranking and an explicit cut-off. No network, no
+fixtures.

package/skills/viral-score/evals/cases.yaml

@@ -0,0 +1,50 @@
+skill: viral-score
+
+should_trigger:
+  - prompt: "Score this reel — is it worth publishing?"
+    why: Core ask — a single clip judged against the rubric, verdict required.
+  - prompt: "I cut 20 clips from yesterday's episode. Rank them and tell me which ones to post."
+    why: Batch mode — ranking plus the cut-off line, which only this skill produces.
+  - prompt: "Order these shorts from best to worst."
+    why: Comparison with no scoring keyword; ordering clips requires a shared instrument.
+  - prompt: "Here's the transcript of a 2h podcast. Which passages would make good shorts?"
+    why: The pre-render case the skill exists for — score candidates before anything is edited.
+  - prompt: "Valora este reel y dime si lo publico o lo descarto."
+    why: Spanish — same core ask, publish/discard verdict.
+  - prompt: "This clip feels flat to me but I can't say why. Is it me?"
+    why: Non-obvious — a vague quality doubt resolves into criterion scores and named weaknesses.
+  - prompt: "Why did this short underperform? It seemed strong when I made it."
+    why: Non-obvious — retrospective diagnosis against the same criteria, especially hook and context independence.
+
+should_not_trigger:
+  - prompt: "Write the caption and hashtags for this Reel."
+    route_to: shortform-packaging
+    why: Upload-form copy for a clip already chosen, not the decision to choose it.
+  - prompt: "Give me ten ideas for shorts about discipline."
+    route_to: shortform-ideation
+    why: Inventing angles, upstream of anything that can be scored.
+  - prompt: "Burn in the subtitles and add B-roll to this clip."
+    route_to: shortform-editing
+    why: Executing the edit; scoring is what decides whether the edit is worth doing.
+  - prompt: "How often should I post on this channel, and at what times?"
+    route_to: shortform-strategy
+    why: Channel cadence over time, not the merit of one artifact.
+  - prompt: "Design a thumbnail for my YouTube video."
+    route_to: youtube-thumbnails
+    why: A different surface and a different artifact; this rubric scores the clip itself.
+
+capability:
+  - prompt: "Score this 18s clip: it opens mid-sentence with 'o sea, entonces lo que pasa es que…', has a 4s pause in the middle, and ends without resolving the point."
+    must_include:
+      - "a score for all ten criteria"
+      - "the weak-hook penalty applied for opening mid-sentence"
+      - "the long-pause penalty"
+      - "the unsatisfying-ending penalty"
+      - "a final score clamped to 0-100 after penalties"
+      - "a Publish / Review / Discard verdict"
+  - prompt: "Here are 6 clips from one episode with their transcripts. Rank them."
+    must_include:
+      - "a Viral Score for every clip"
+      - "a ranking from highest to lowest"
+      - "an explicit cut-off point below which publishing is not worth it"
+      - "strengths and weaknesses per clip, tied to what happens in it"