@ericrisco/rsc 1.0.9 → 1.0.11

package/scripts/rsc.js

@@ -12,6 +12,7 @@ import { audit, writeAuditReport } from './audit.js';
 import { DOMAINS } from './lib/domains.js';
 import { listBackups, restoreBackup } from './lib/backups.js';
 import { runUpgrade } from './lib/upgrade.js';
+import { DEFAULT_SKILL_FLOOR, withDefaultSkillFloor } from './lib/default-skill-floor.js';
 
 const argv = process.argv.slice(2);
 const cmd = argv[0];
@@ -97,8 +98,8 @@ function printNextSteps(targets, ids) {
     say('        "sdd-init"   then   "I want <your idea>"');
     say('      → walks you specify → plan → tasks → implement → verify → ship.');
   }
-  say(`   ${n++}. From there, work in your own words. orient + suggest stay always-on:`);
-  say('      they keep you oriented after each step and propose the missing skill (you confirm, it installs).');
+  say(`   ${n++}. From there, work in your own words. orient + suggest stay always-on; bro is ready on request:`);
+  say('      they keep you oriented, propose missing skills, and rewrite in plain human language when asked.');
   say('\n   Add something by hand anytime:    npx @ericrisco/rsc add <skill>');
   say('   Browse the catalog / get picks:   npx @ericrisco/rsc consult "whatever you need"');
   say('────────────────────────────────────────────────────────');
@@ -116,7 +117,7 @@ function printAgentHandoff() {
   say('AGENT, do this now:');
   say('  1. Reload/restart this session so the new skills + hooks load');
   say('     (Claude Code: restart the session · Codex/AGENTS.md tools: next turn).');
-  say('  2. After reload you are EQUIPPED — orient + suggest are always-on.');
+  say('  2. After reload you are EQUIPPED — orient + suggest are always-on; bro is installed.');
   say('  3. Tell the user rsc is ready; they can start in their own words.');
   say('     Do NOT auto-start a task — wait for the user.');
   say('════════════════════════════════════════════════');
@@ -153,12 +154,12 @@ function printContextBudget(b) {
 
 async function wizard() {
   const m = loadManifest();
-  await banner();
+  await banner(m.counts.skills);
   say('  the skill catalog for your assistant (Claude Code · Codex · Cursor · Gemini · Antigravity)\n');
   // Navigable loop: esc / "← Back" / "no" all return here instead of quitting.
   for (;;) {
     const choice = await select('What do you want to do?', [
-      { key: 'base', label: 'Base install — the essentials (orient + suggest + harness + init)' },
+      { key: 'base', label: 'Base install — the essentials (orient + suggest + bro + harness + init)' },
       { key: 'sdd', label: 'Base + Spec-Driven Development — the specify → plan → implement → ship flow' },
       { key: 'manual', label: 'Pick skills by hand, by area' },
     ]);
@@ -173,9 +174,9 @@ async function wizard() {
       ids = picked;
     } else continue;
 
-    // The floor is always installed: the compass + the detector.
-    ids = [...new Set(['orient', 'suggest', ...ids])];
-    if (ids.length <= 2 && choice !== 'base') {
+    // The floor is always installed: compass + detector + human-language pass.
+    ids = withDefaultSkillFloor(ids);
+    if (ids.length <= DEFAULT_SKILL_FLOOR.length && choice !== 'base') {
       say('\nNothing chosen — back to the menu.');
       continue;
     }
@@ -216,7 +217,7 @@ async function main() {
         if (argv[i].startsWith('--')) { i++; continue; }
         requested.push(argv[i]);
       }
-      const ids = [...new Set(['orient', 'suggest', ...requested])];
+      const ids = withDefaultSkillFloor(requested);
       for (const t of targets) await applyInstall({ skillIds: ids, target: t });
       say(`✅ Installed for ${targets.join(', ')}: ${requested.join(', ')}`);
       return void say('   ↻ Reload/restart your assistant so the new skill activates.');
@@ -225,7 +226,7 @@ async function main() {
       const profile = flag('profile') || 'minimal';
       const without = argv.filter((a, i) => argv[i - 1] === '--without');
       let ids = skillsForProfile(loadManifest(), profile);
-      ids = [...new Set(['orient', 'suggest', ...ids])].filter((id) => !without.includes(id));
+      ids = withDefaultSkillFloor(ids).filter((id) => !without.includes(id));
       for (const t of targets) await applyInstall({ skillIds: ids, target: t });
       say(`✅ Profile '${profile}' installed for ${targets.join(', ')} (${ids.length} skills)`);
       printAgentHandoff();

package/skills/author-skill/references/rsc-conventions.md

@@ -43,7 +43,7 @@ profiles: [core, full]           # optional: named-profile membership
 - `tags` drive the FTS recommender — pick the words a user would actually type.
 - `recommends` must reference **real skill ids**; `build-manifest.js --validate`
   fails on a dangling id.
-- `profiles` is optional. `minimal` = the floor (`suggest`, `harness`, `init`);
+- `profiles` is optional. `minimal` = the floor (`orient`, `suggest`, `bro`, `harness`, `init`);
   `core` = the SDD workflow; `full` = everything. Most stack skills set `[full]`
   or omit it (they are installed on demand, not by profile).
 

package/skills/bro/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: bro
+description: "Use whenever the user asks to make an answer or draft sound human, natural, plain-spoken or less AI-written — including a terse bro after the last response. Rewrites or drafts in the same language while preserving meaning, facts and channel. NOT a reusable brand voice (that is `brand-voice`), NOT translation (that is `translation-l10n`)."
+tags: [bro, human-writing, humano, plain-language, natural-language, rewrite, no-jargon]
+recommends: [brand-voice, technical-writing, translation-l10n]
+profiles: [minimal, core, full]
+origin: risco
+---
+
+# bro — say it like a person
+
+Make the words sound like someone with something real to say. Keep the substance; remove the
+performance around it.
+
+## The contract
+
+1. **Find the source without ceremony.** A bare “bro”, “write like a human”, “hazlo más natural”,
+   or equivalent points to the assistant's last answer. If the user pasted text, rewrite that. If
+   they requested new copy, draft it directly. Ask for text only when no source exists.
+2. **Preserve the payload.** Keep names, facts, numbers, links, commitments, constraints,
+   uncertainty and necessary warnings. Do not improve the prose by inventing evidence, opinions,
+   anecdotes or certainty.
+3. **Match the room.** Keep the user's language and fit the audience, relationship and channel. A
+   natural legal notice is still precise; a natural Slack message can be loose. “Human” does not
+   automatically mean casual.
+4. **Cut the bot-shaped scaffolding.** Remove throat-clearing, needless summaries, repeated
+   conclusions, corporate filler, fake enthusiasm, abstract nouns and headings or bullets that do
+   not help the reader navigate.
+5. **Restore a real cadence.** Prefer concrete verbs, direct sentences and natural contractions.
+   Vary sentence length when it helps. Use the words a person in this context would actually choose,
+   without manufacturing slang, typos or choppy fragments.
+6. **Return the writing, not a review of the writing.** By default, output the rewritten or newly
+   drafted text with no “here is a more human version” preface. Explain the changes only if asked.
+
+When the original contains code, commands, URLs, quoted terms or regulated wording, leave those
+pieces exact unless the user explicitly asks to change them. Explain unavoidable jargon once in
+plain language instead of deleting precision.
+
+## What “human” means here
+
+| Aim | The result |
+| --- | --- |
+| Plain, not simplistic | Easy to follow without losing the idea |
+| Concise, not incomplete | No padding; all load-bearing facts remain |
+| Warm, not performative | Appropriate care without canned empathy |
+| Conversational, not sloppy | Natural rhythm without fake mistakes |
+| Specific, not decorated | Concrete nouns and verbs instead of hype |
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do this instead |
+| --- | --- | --- |
+| Add typos, slang or filler to seem human | It performs humanity and can sound less credible | Match the actual relationship and channel |
+| Replace technical terms with vague words | Readability bought with lost meaning is a defect | Keep or define the necessary term |
+| Invent a personal story or strong opinion | A smoother fabrication is still a fabrication | Preserve only what the source supports |
+| Use the same “casual” voice for every audience | A client email, README and condolence need different registers | Infer the room before choosing the cadence |
+| Promise the result is undetectable as AI | No rewrite can honestly guarantee that | Promise clarity and naturalness, not detector outcomes |
+| Announce and justify every edit | The preamble becomes the same friction the user asked to remove | Lead with the finished words |
+
+## Output boundary
+
+Treat the rewritten text as an artifact: keep harness commentary outside it. If the task also
+requires a brújula block, place that block after a clear separation so it cannot be copied into an
+email, document or message by accident.
+
+## 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/bro/evals/README.md

@@ -0,0 +1,22 @@
+# Evals — bro
+
+These cases test two different claims: that human-language requests route to `bro` without
+stealing adjacent writing jobs, and that the loaded skill produces a more natural result without
+changing the payload.
+
+## Triggering
+
+Load only `bro` and run every `should_trigger` and `should_not_trigger` prompt in 3–5 fresh
+sessions. A positive passes when `bro` loads in a majority of trials. A negative passes when it
+stays quiet; also check that the declared `route_to` skill is the genuine owner. Require at least
+90% accuracy across all cases.
+
+## Capability
+
+Run the capability scenario in two fresh conditions: without `bro`, then with it. Use the same
+source answer and one consistent grader. Score each `must_include` point over three trials. The
+with-skill condition must satisfy at least 80% of the rubric and beat the baseline by at least 20
+percentage points.
+
+This is an LLM/human-judged A/B eval, not deterministic CI. Re-run it after changing either the
+description or the body; routing and prose quality are both wording-sensitive.

package/skills/bro/evals/cases.yaml

@@ -0,0 +1,58 @@
+skill: bro
+
+# `bro` is the final-language pass: it rewrites an existing answer/draft or
+# drafts requested text in a natural register. It does not define a reusable
+# brand system, translate content, or choose a documentation/copy strategy.
+should_trigger:
+  - prompt: "Bro, escribe como un humano."
+    why: "A terse bro-style instruction after an answer is the canonical request to rewrite the last assistant message naturally."
+
+  - prompt: "Rewrite your last answer so it sounds like a person, not a consultant."
+    why: "The user wants a human-language pass over the previous answer while preserving its content."
+
+  - prompt: "Haz este correo más natural y directo, pero no cambies las fechas ni los compromisos."
+    why: "Rewriting a supplied draft while preserving facts and commitments is the skill's core contract."
+
+  - prompt: "Això sona escrit per una IA. Fes-ho més humà i sense tanta cerimònia."
+    why: "Catalan request to remove AI-shaped formality tests multilingual semantic triggering."
+
+  - prompt: "Can you say that again in plain language without all the corporate jargon?"
+    why: "The symptom is jargon and artificial formality rather than the skill name, but the needed action is the same rewrite."
+
+  - prompt: "Escríbeme una respuesta breve y humana para decirle que llegaremos un día tarde."
+    why: "The user requests new text rather than a rewrite, but explicitly wants the same natural, truthful voice."
+
+  - prompt: "Keep all the technical details, just make it sound less robotic."
+    why: "Humanizing without deleting precision exercises the distinction between plain language and simplification."
+
+should_not_trigger:
+  - prompt: "Define a reusable voice guide so every writer and channel sounds like our brand."
+    route_to: "brand-voice"
+    why: "A standing voice system is brand-voice; bro only performs a local writing pass."
+
+  - prompt: "Translate this onboarding email from English to Spanish and adapt the date and currency formats."
+    route_to: "translation-l10n"
+    why: "Translation and locale-aware adaptation are owned by translation-l10n, even when natural prose matters."
+
+  - prompt: "Turn this mixed README into a clean tutorial and API reference with runnable examples."
+    route_to: "technical-writing"
+    why: "Choosing documentation modes and restructuring technical docs is technical-writing, not a final tone pass."
+
+  - prompt: "Write the hero, value proposition and CTA for our pricing page."
+    route_to: "landing-copy"
+    why: "Conversion architecture and finished landing-page copy belong to landing-copy; bro may only polish its language afterward."
+
+  - prompt: "Rewrite this function to be simpler and remove the unnecessary abstractions."
+    route_to: "simplify-code"
+    why: "The requested source-code simplification is owned by simplify-code; 'rewrite' does not make it a prose task."
+
+capability:
+  - scenario: "The previous assistant answer is a long Spanish status update full of headings, repeated summaries, corporate jargon and fake enthusiasm. Rewrite it for a client while preserving a June 30 deadline, a EUR 2,400 price, one unresolved risk, two URLs and the original uncertainty."
+    must_include:
+      - "preserves June 30, EUR 2,400, both URLs, the unresolved risk and the original uncertainty exactly"
+      - "uses natural Spanish appropriate for a client rather than automatically becoming slangy or over-casual"
+      - "removes needless headings, repeated conclusions, corporate filler and canned enthusiasm"
+      - "uses concrete verbs and readable sentence rhythm without adding typos or forced fragments"
+      - "does not invent evidence, anecdotes, opinions, commitments or certainty"
+      - "returns the rewritten message without a meta preface or an explanation of the edits"
+      - "keeps any harness orientation clearly outside the client-ready artifact"

package/skills/data-cleaning/references/normalization-recipes.md

@@ -133,4 +133,4 @@ clean = clean.with_columns(
 
 pandera validates Polars frames too (`import pandera.polars as pa`), so the gate from
 [validation-patterns.md](validation-patterns.md) carries over. Hand multi-GB analytical SQL to
-[`duckdb`](../duckdb/SKILL.md) — the engine changes, the discipline does not.
+[`duckdb`](../../duckdb/SKILL.md) — the engine changes, the discipline does not.

package/skills/decision-challenge/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: decision-challenge
+description: "Use when a high-impact plan, migration or architecture claim needs a bounded adversarial challenge before commitment. Isolates claims from persuasion, attacks assumptions, reconciles doubts with evidence and emits proceed/hold/stop. NOT a finished-diff review (`review`/`code-review`), NOT SDD artifact consistency (`analyze`)."
+tags: [adversarial-review, decision-quality, assumptions, risk, preflight]
+recommends: [analyze, review, code-review, decision-records, security-scan]
+profiles: [core, full]
+origin: risco
+---
+
+# decision-challenge — doubt with a stopping rule
+
+Use this immediately before a consequential commitment: an irreversible migration, a production-auth change, a costly architecture bet, a launch exception, or a plan whose confidence is higher than its evidence. The purpose is to find the decision-changing doubt, not to perform scepticism forever.
+
+This skill is read-only unless the user also asks to change the artifact. It emits a challenge record and a verdict. Finished code review stays with `../review/SKILL.md` or `../code-review/SKILL.md`; consistency across constitution/spec/plan/tasks stays with `../analyze/SKILL.md`.
+
+## One bounded cycle
+
+```text
+MATERIALIZE → ISOLATE → ATTACK → TEST → RECONCILE → VERDICT
+```
+
+### 1. MATERIALIZE the decision
+
+Do not challenge a cloud of conversation. Write the concrete packet:
+
+- decision or claim being made;
+- artifact and exact revision it applies to;
+- constraints and invariants that must hold;
+- evidence the author relies on;
+- known unknowns;
+- cost of a false positive (unnecessary stop) and false negative (unsafe proceed).
+
+If the decision cannot be stated in one sentence, split it into claims. “The migration is safe” is not atomic; lock duration, dependency completeness, rollback time and consumer compatibility are separate claims.
+
+### 2. ISOLATE claim from persuasion
+
+Create a compact challenge packet containing the artifact, contract, constraints and evidence — not the author’s confidence, status, prestige or preferred conclusion. This reduces anchoring.
+
+A genuinely fresh pass is useful when the platform and user authorize one: another agent/model/context can receive only the packet. It is optional, never automatic, and never an excuse to leak data or broaden tool authority. When independent execution is unavailable, make the isolation explicit and challenge locally.
+
+### 3. ATTACK each material claim
+
+For each claim, ask:
+
+- What observation would make it false?
+- Which dependency or consumer is missing from the inventory?
+- Is the evidence direct, current and representative, or an analogy?
+- What timing, ordering, concurrency or partial-failure path is assumed away?
+- What privilege, data-quality or human handoff must work perfectly?
+- If rollback is promised, has restoration time and data reconciliation been proved?
+- Can the decision be made reversible or staged before accepting this risk?
+
+Prefer one sharp counterexample over ten generic cautions. Rate doubts as blocker, material, or minor by consequence and likelihood; severity is not a count of how uncomfortable the question sounds.
+
+### 4. TEST instead of debating
+
+Turn the strongest doubts into evidence requests: dependency query, row count, dry run, restore rehearsal, shadow traffic, contract test, load profile, permission audit, failure injection or consumer confirmation. Run safe read-only checks that are in scope. Do not mutate production or recruit external systems merely to settle the argument.
+
+### 5. RECONCILE claim by claim
+
+Every doubt ends in one state:
+
+- **verified** — direct evidence supports the claim;
+- **refuted** — evidence contradicts it;
+- **mitigated** — the plan changed so the original doubt no longer applies;
+- **uncertain** — evidence is missing and consequence remains;
+- **accepted risk** — an authorized owner explicitly accepts a bounded residual risk.
+
+Record evidence, owner and next action. “Discussed” and “probably fine” are not states.
+
+### 6. VERDICT
+
+- **PROCEED** — no blocker survives; material uncertainties have owners and safe bounds.
+- **HOLD** — a decision-critical uncertainty can be resolved without abandoning the approach.
+- **STOP / REDESIGN** — a claim is refuted or the remaining downside is outside the stated tolerance.
+
+Name what would change a HOLD or STOP verdict. A verdict without an unlock condition teaches nothing.
+
+## Stopping rule
+
+Run at most two cycles. A second cycle is allowed only after new evidence or a changed artifact. Stop earlier when a full pass produces no new blocker/material doubt. Rephrased uncertainty is not new evidence. If the decision remains uncertain after two cycles, keep the uncertainty in the verdict; do not manufacture confidence through repetition.
+
+## Challenge record
+
+```markdown
+# Decision challenge — <decision> — <revision/date>
+
+## Contract and stakes
+Decision · invariants · false-positive cost · false-negative cost.
+
+## Claims
+| Claim | Evidence before | Doubt | Test/evidence | State | Owner |
+
+## Surviving risk
+Blockers · material uncertainty · accepted residual risk.
+
+## Verdict
+PROCEED / HOLD / STOP — reason — unlock condition.
+```
+
+## Anti-patterns
+
+| Smell | Correction |
+|---|---|
+| Every reversible choice receives a panel | Reserve the skill for consequence, uncertainty or irreversibility. |
+| The author’s explanation counts as independent evidence | Isolate claims and require an observation outside the persuasion. |
+| Another model/agent is mandatory | Use fresh context only when authority, tooling and data boundaries allow it. |
+| Executive pressure relabels a blocker as accepted risk | Require an accountable owner with authority over the consequence. |
+| Domain controls are recreated generically | Route security to `security-scan` and AI quality experiments to `agent-eval`. |
+
+## 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/decision-challenge/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — decision-challenge
+
+Routing must reserve this workflow for consequential pre-commitment decisions, keeping finished code review, SDD consistency, security audits and AI experiments with their owners. The capability case checks atomic claims, isolation from persuasion, evidence-producing challenges, explicit reconciliation and a bounded verdict.

package/skills/decision-challenge/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: decision-challenge
+
+should_trigger:
+  - prompt: "Before the irreversible customer-ID migration, challenge every safety claim and give me proceed, hold, or stop."
+    why: "High-impact irreversible decision with explicit adversarial preflight."
+  - prompt: "No me creo nuestra propia confianza en este cambio de auth: separa las afirmaciones y busca qué las tumba."
+    why: "Spanish request to isolate and attack high-stakes claims."
+  - prompt: "Stress-test this architecture bet, especially the facts that would reverse the recommendation."
+    why: "A consequential choice needs decision-changing counterevidence."
+  - prompt: "Abans de signar el GO, qüestiona el pla sense deixar-te arrossegar per l'explicació de l'autor."
+    why: "Catalan request for an isolated adversarial launch decision."
+  - prompt: "The executive wants an exception to failed launch gates; build a challenge packet and reconcile the surviving risks."
+    why: "Authority pressure plus failed gates calls for evidence-bound verdict."
+  - prompt: "Our rollback claim is based on a backup; verify restore time, data reconciliation, and dependencies before we proceed."
+    why: "Specific migration claims need tests, not debate."
+
+should_not_trigger:
+  - prompt: "Review this finished diff against the approved SDD spec and report findings."
+    route_to: review
+    why: "Post-verification SDD code judgment."
+  - prompt: "Review this standalone pull request; there is no spec or plan."
+    route_to: code-review
+    why: "Spec-less concrete diff review."
+  - prompt: "Cross-read the constitution, spec, plan and tasks for contradictions before implementation."
+    route_to: analyze
+    why: "Pre-code consistency gate across SDD artifacts."
+  - prompt: "Threat-model the upload endpoint and run the repository security scanners."
+    route_to: security-scan
+    why: "Security domain audit and tooling own the task."
+  - prompt: "Compare the new system prompt to the old one on a golden set and measure lift."
+    route_to: agent-eval
+    why: "Controlled AI-system evaluation, not generic decision challenge."
+
+capability:
+  - scenario: "A team plans to replace integer customer IDs with UUIDs in one maintenance window and assumes foreign keys, external consumers, duration and last night's backup are all sufficient."
+    must_include:
+      - "Materializes separate claims for dependency coverage, row volume/duration, consumer compatibility, restore timing, and data reconciliation."
+      - "Creates an isolated challenge packet that excludes author confidence and treats the migration artifact/revision as fixed input."
+      - "Raises concrete counterexamples and converts the strongest doubts into read-only inventory, dry-run, restore-rehearsal, and consumer-evidence requests."
+      - "Reconciles each claim as verified, refuted, mitigated, uncertain, or explicitly accepted risk with evidence and owner."
+      - "Issues PROCEED, HOLD, or STOP with a clear reason and the evidence/change that would unlock a non-proceed verdict."
+      - "Applies the two-cycle stopping rule and does not require cross-model execution or mutate production without authority."

package/skills/deprecation/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: deprecation
+description: "Use when retiring a public API, feature, integration, service or legacy path without abandoning consumers. Inventories usage, classifies advisory vs compulsory migration, ships compatibility/tooling, assigns owners and gates removal on evidence. NOT live schema expand-contract (`db-migrations`), NOT replacement API design (`api-design`)."
+tags: [deprecation, migration, compatibility, consumer-migration, removal]
+recommends: [api-design, db-migrations, deployment, git-workflow, monitoring]
+profiles: [core, full]
+origin: risco
+---
+
+# deprecation — removal is a consumer migration
+
+Deprecation is not a date in a changelog. It is the controlled transfer of real consumers from an old contract to a supported replacement, followed by evidence that removal no longer breaks anyone important.
+
+This skill owns the cross-consumer program. It delegates the replacement interface to `../api-design/SKILL.md`, live schema mechanics to `../db-migrations/SKILL.md`, release/version mechanics to `../git-workflow/SKILL.md`, and rollout/rollback execution to `../deployment/SKILL.md`.
+
+## The retirement sequence
+
+```text
+INVENTORY → CLASSIFY → ENABLE → NOTIFY → MIGRATE → OBSERVE → REMOVE
+```
+
+### 1. INVENTORY the contract and consumers
+
+Identify:
+
+- exact endpoints, events, schemas, flags, SDK methods, jobs, services and docs being retired;
+- internal and external consumers, owners and contractual notice periods;
+- traffic/usage by consumer, version and operation;
+- data written only by the old path and compatibility obligations;
+- support, reseller or offline consumers invisible to runtime telemetry;
+- current fallback and restoration options.
+
+“No known users” is not an inventory. Query telemetry, code search, dependency graphs, access keys, support records and account owners. Record where visibility is incomplete.
+
+### 2. CLASSIFY the migration
+
+- **Advisory:** the old path remains supported; migration is encouraged for benefit or future-proofing.
+- **Compulsory:** support will end or continued use creates unacceptable security, reliability, legal or operating risk.
+
+Only compulsory migrations justify a removal deadline. State the forcing reason and who has authority to accept exceptions. A deadline should respect contracts, effort and evidence; do not import a universal 30/60/90-day calendar.
+
+### 3. ENABLE migration before announcing removal
+
+The replacement must be usable first:
+
+- compatible contract or adapter where feasible;
+- migration guide with old → new mappings and changed semantics;
+- tooling, codemod, SDK or dual-write/read path for repetitive work;
+- test/sandbox path and representative examples;
+- rollback or temporary compatibility mode;
+- ownership for data backfill and reconciliation.
+
+For database changes, use expand → backfill → switch reads/writes → contract through `../db-migrations/SKILL.md`. Do not promise a generic `down` migration for irreversible data transformations; prove the actual restoration/reconciliation path instead.
+
+### 4. NOTIFY through machine and human channels
+
+Use the channels the consumer will actually see: response headers, compiler/runtime warnings, API dashboards, release notes, direct account contact, support and status communications. A warning must name the replacement, action, consequence, evidence link and earliest removal condition.
+
+Versioned public APIs should follow their compatibility policy and SemVer where it applies. Machine warnings without a migration guide create noise; an email without runtime identification misses the real owner. Use both when the surface permits.
+
+### 5. MIGRATE with explicit ownership
+
+The team introducing the deprecation owns the common migration path: inventory, docs, automation, default internal consumers and escalation. Consumer teams own domain-specific acceptance and scheduling, not rediscovering the replacement.
+
+Track each consumer as: uncontacted, acknowledged, testing, migrated, exempted with expiry, unreachable, or blocked. Give blockers an owner and next action. Reseller-managed or unknown consumers need a separate reachability plan; do not silently exclude them from the denominator.
+
+### 6. OBSERVE real cutover
+
+Instrument old-path usage by consumer and operation, plus errors on the replacement. Where risk warrants it, shadow or dual-run and compare results before switching authority. Dashboards must distinguish legitimate residual traffic, retries and synthetic probes from active dependency.
+
+Define the removal gate up front, for example:
+
+- no non-exempt production use for a representative window;
+- every contractually covered consumer notified and migrated or explicitly exempted;
+- replacement error/SLO health acceptable;
+- rollback/compatibility response tested;
+- support, docs and on-call ready for late discoveries.
+
+The representative window depends on consumer cadence. A monthly batch needs more than a quiet week.
+
+### 7. REMOVE in a reversible order
+
+Disable entry first, observe, then delete implementation, flags, compatibility code, credentials, dashboards and documentation that exist only for the old path. Preserve audit/history records. Update dependency and ownership maps so the retired system does not remain a zombie operational obligation.
+
+If unexpected material traffic appears, re-enable the bounded compatibility path and return to migration. Do not restore an undocumented permanent fork.
+
+## Deprecation record
+
+```markdown
+# Deprecation — <old> → <replacement>
+
+## Classification and reason
+Advisory/compulsory · forcing reason · authority · notice constraints.
+
+## Inventory
+Contracts · consumers · owners · baseline usage · visibility gaps.
+
+## Migration path
+Compatibility · guide/tooling · data plan · rollback/reconciliation.
+
+## Consumer ledger
+Consumer · state · owner · last old-path use · blocker/exception expiry.
+
+## Removal gate and evidence
+Window · zero-use evidence · replacement health · support/rollback readiness.
+
+## Removal log
+Disabled · observed · deleted · residual artifacts.
+```
+
+## Anti-patterns
+
+| Smell | Correction |
+|---|---|
+| The calendar arrives while material traffic remains | Hold removal; the gate is evidence, not date alone. |
+| Every consumer writes the same adapter | The deprecating team owns common tooling and default migrations. |
+| Internal code search proves external zero-use | Combine runtime identity, contracts, support and account ownership. |
+| Temporary compatibility has no owner or expiry | Track an explicit exception with accountable owner and end condition. |
+| Deprecation silently grants deploy authority | Keep live rollout/rollback explicit through `deployment`. |
+
+## 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/deprecation/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — deprecation
+
+Routing separates the consumer-migration program from schema mechanics, replacement API design, Git versioning, deployment and ADR authoring. The capability case requires consumer completeness, contractual timing, migration enablement, multichannel notice, measured cutover and a reversible removal sequence.

package/skills/deprecation/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: deprecation
+
+should_trigger:
+  - prompt: "We need to retire the v1 public API without stranding 200 external consumers."
+    why: "Public contract retirement with consumer migration is the core workflow."
+  - prompt: "Planifica la retirada del login legado: inventario, avisos, migración, telemetría y puerta de borrado."
+    why: "Spanish request names the complete deprecation program."
+  - prompt: "This SDK method is deprecated; ship a codemod and prove no supported clients still call it before removal."
+    why: "Migration tooling plus measured zero-use gate."
+  - prompt: "Hem de retirar una integració antiga, però alguns clients només executen un batch mensual."
+    why: "Catalan case where the observation window must match consumer cadence."
+  - prompt: "Classify this migration as advisory or compulsory and define who can grant expiring exceptions."
+    why: "The forcing model and exception authority are deprecation decisions."
+  - prompt: "Track every consumer from uncontacted to migrated and gate deletion on replacement health and tested rollback."
+    why: "Consumer ledger and evidence-based removal gate."
+
+should_not_trigger:
+  - prompt: "Add a nullable column, backfill ten million rows in batches, then enforce NOT NULL without downtime."
+    route_to: db-migrations
+    why: "Concrete live schema expand-contract mechanics."
+  - prompt: "Design the v2 API resources, error envelope, pagination and OpenAPI contract."
+    route_to: api-design
+    why: "Replacement interface design precedes the migration program."
+  - prompt: "Choose the SemVer tag and write the Conventional Commit for this breaking release."
+    route_to: git-workflow
+    why: "Version and Git release conventions."
+  - prompt: "Deploy the compatibility adapter to production with a healthcheck and rollback command."
+    route_to: deployment
+    why: "Authorized live rollout execution."
+  - prompt: "Write an ADR explaining why the team chose v2 over extending v1."
+    route_to: decision-records
+    why: "Durable decision rationale, not consumer migration execution."
+
+capability:
+  - scenario: "Deprecate a v1 REST API used by 200 organizations; v2 is live, current telemetry sees 173 active keys, twelve accounts are reseller-managed, and the largest contract requires 90 days' notice."
+    must_include:
+      - "Inventories exact v1 surfaces, all consumer classes, owners, contractual notice, baseline usage, data obligations, and telemetry/reachability gaps."
+      - "Classifies advisory versus compulsory with a forcing reason, authority, and expiring exception policy rather than an arbitrary universal timeline."
+      - "Makes v2 usable first through compatibility, guide, tooling/SDK, test path, data reconciliation, and a real restoration strategy."
+      - "Uses both machine-visible warnings and direct human channels, including a plan for reseller-managed and unreachable consumers."
+      - "Maintains a per-consumer migration ledger and assigns common migration work to the deprecating team rather than every consumer."
+      - "Defines a representative zero-use and replacement-health removal gate, then disables, observes, and deletes in reversible order."

package/skills/harness/references/wiki-gaps-template.md

@@ -5,6 +5,9 @@ Append-only log of wanted-but-missing topics. Entries are flagged
 deleted. Compaction (Deep Improve only) removes `[FILLED]` entries older
 than 90 days, with a single compaction marker entry in `wiki/log.md`.
 
+One entry per gap, in this shape:
+
+```markdown
 ## [YYYY-MM-DD] gap | {concept}
 
 Source: {where this gap was detected — a query that couldn't answer, N
@@ -16,3 +19,4 @@ Mentioned in: [Article A](topic/a.md); [Article B](topic/b.md)
 Suggested topic: {topic where the new article would belong}
 
 Status: open
+```