@ericrisco/rsc 1.0.10 → 1.0.11

package/scripts/routing-audit.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRanker } from './consult.js';
+import { loadManifest } from './lib/manifest.js';
+import { buildTextCorpus, descriptionCollisions } from './lib/text-rank.js';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const FLOORS = {
+  rank1: 44,
+  top5: 70,
+  routedTop5: 85,
+  maxNegativeSelfRank1: 6,
+  maxCollision: 0.80,
+};
+
+function unquote(value) {
+  const trimmed = value.trim();
+  if (trimmed.startsWith('"')) return JSON.parse(trimmed);
+  return trimmed.replace(/^['"]|['"]$/g, '');
+}
+
+export function loadRoutingCases(root = ROOT) {
+  const cases = [];
+  const skillsRoot = join(root, 'skills');
+  for (const skill of readdirSync(skillsRoot).sort()) {
+    const file = join(skillsRoot, skill, 'evals', 'cases.yaml');
+    if (!existsSync(file)) continue;
+    const lines = readFileSync(file, 'utf8').split(/\r?\n/);
+    let section = '';
+    for (let index = 0; index < lines.length; index += 1) {
+      const line = lines[index];
+      if (/^should_trigger:/.test(line)) section = 'positive';
+      else if (/^should_not_trigger:/.test(line)) section = 'negative';
+      else if (/^capability:/.test(line)) section = '';
+      const prompt = line.match(/^  - prompt:\s*(".*")$/);
+      if (!prompt || !section) continue;
+
+      let routeTo = null;
+      if (section === 'negative') {
+        for (let next = index + 1; next < Math.min(lines.length, index + 8); next += 1) {
+          if (/^  - prompt:|^[A-Za-z_]+:/.test(lines[next])) break;
+          const route = lines[next].match(/^\s+route_to:\s*(.+?)\s*$/);
+          if (route) {
+            routeTo = unquote(route[1]);
+            break;
+          }
+        }
+      }
+      cases.push({ skill, section, prompt: unquote(prompt[1]), routeTo });
+    }
+  }
+  return cases;
+}
+
+function percentage(value, total) {
+  return total ? (100 * value) / total : 0;
+}
+
+function singleCatalogRoute(routeTo, ids) {
+  if (!routeTo || routeTo === 'none' || routeTo.startsWith('external:')) return null;
+  if (/[|,]/.test(routeTo) || routeTo.includes(' or ')) return null;
+  return ids.has(routeTo) ? routeTo : null;
+}
+
+export async function auditRouting(manifest, cases) {
+  const ids = new Set(manifest.skills.map(({ id }) => id));
+  const ranker = await createRanker(manifest);
+  const result = {
+    positives: 0,
+    rank1: 0,
+    top3: 0,
+    top5: 0,
+    negatives: 0,
+    negativeSelfRank1: 0,
+    routed: 0,
+    routedTop5: 0,
+    routeBeatsOwner: 0,
+    missedBySkill: new Map(),
+  };
+
+  try {
+    for (const row of cases) {
+      const ranked = ranker.rank(row.prompt).map(({ id }) => id);
+      if (row.section === 'positive') {
+        result.positives += 1;
+        const position = ranked.indexOf(row.skill);
+        if (position === 0) result.rank1 += 1;
+        if (position >= 0 && position < 3) result.top3 += 1;
+        if (position >= 0 && position < 5) result.top5 += 1;
+        else result.missedBySkill.set(row.skill, (result.missedBySkill.get(row.skill) || 0) + 1);
+        continue;
+      }
+
+      result.negatives += 1;
+      if (ranked[0] === row.skill) result.negativeSelfRank1 += 1;
+      const target = singleCatalogRoute(row.routeTo, ids);
+      if (!target) continue;
+      result.routed += 1;
+      const targetPosition = ranked.indexOf(target);
+      const ownerPosition = ranked.indexOf(row.skill);
+      if (targetPosition >= 0 && targetPosition < 5) result.routedTop5 += 1;
+      if (targetPosition >= 0 && (ownerPosition < 0 || targetPosition < ownerPosition)) {
+        result.routeBeatsOwner += 1;
+      }
+    }
+  } finally {
+    ranker.close();
+  }
+  return result;
+}
+
+async function main() {
+  const manifest = loadManifest();
+  const cases = loadRoutingCases();
+  const result = await auditRouting(manifest, cases);
+  const collisions = descriptionCollisions(buildTextCorpus(manifest.skills), 0.45);
+  const rates = {
+    rank1: percentage(result.rank1, result.positives),
+    top3: percentage(result.top3, result.positives),
+    top5: percentage(result.top5, result.positives),
+    negativeSelfRank1: percentage(result.negativeSelfRank1, result.negatives),
+    routedTop5: percentage(result.routedTop5, result.routed),
+    routeBeatsOwner: percentage(result.routeBeatsOwner, result.routed),
+  };
+
+  console.log(`routing-audit: ${manifest.skills.length} skills · ${cases.length} prompts`);
+  console.log(
+    `positive recall: rank-1 ${rates.rank1.toFixed(1)}% · top-3 ${rates.top3.toFixed(1)}% · top-5 ${rates.top5.toFixed(1)}%`,
+  );
+  console.log(
+    `negative owner-at-1: ${rates.negativeSelfRank1.toFixed(1)}% · declared route top-5 ${rates.routedTop5.toFixed(1)}% · route beats owner ${rates.routeBeatsOwner.toFixed(1)}%`,
+  );
+  console.log('highest description overlaps:');
+  for (const row of collisions.slice(0, 10)) {
+    console.log(`  ${row.score.toFixed(2)}  ${row.left} ↔ ${row.right}`);
+  }
+  const misses = [...result.missedBySkill].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+  console.log(`largest top-5 gaps: ${misses.slice(0, 10).map(([id, count]) => `${id} (${count})`).join(', ')}`);
+
+  const failures = [];
+  if (rates.rank1 < FLOORS.rank1) failures.push(`rank-1 ${rates.rank1.toFixed(1)}% < ${FLOORS.rank1}%`);
+  if (rates.top5 < FLOORS.top5) failures.push(`top-5 ${rates.top5.toFixed(1)}% < ${FLOORS.top5}%`);
+  if (rates.routedTop5 < FLOORS.routedTop5) {
+    failures.push(`declared-route top-5 ${rates.routedTop5.toFixed(1)}% < ${FLOORS.routedTop5}%`);
+  }
+  if (rates.negativeSelfRank1 > FLOORS.maxNegativeSelfRank1) {
+    failures.push(`negative owner-at-1 ${rates.negativeSelfRank1.toFixed(1)}% > ${FLOORS.maxNegativeSelfRank1}%`);
+  }
+  if (collisions[0]?.score >= FLOORS.maxCollision) {
+    failures.push(`description collision ${collisions[0].score.toFixed(2)} >= ${FLOORS.maxCollision}`);
+  }
+
+  if (failures.length) {
+    console.error(`FAIL: ${failures.join('; ')}`);
+    process.exit(1);
+  }
+  console.log('PASS');
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main();

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/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."