@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/debug/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: debug
+description: "Use when something is broken — a failing or flaky test, crash, wrong result or regression — and the root cause must be reproduced and proven before any fix. On-demand; callable mid-`implement`. NOT a feature to spec or build (that is `specify`/`implement`), NOT the lint/test gate (that is `verify`), NOT adversarial diff reading (that is `review`)."
+tags: [debug, bug, troubleshoot]
+recommends: []
+profiles: [core, full]
+origin: ai-hub
+---
+
+# debug — find the cause before you touch the fix
+
+`debug` is the on-demand diagnosis discipline of the ai-hub Spec-Kit chain. Something is broken — a test
+went red, a crash landed, a result is wrong, a regression appeared — and the strongest pull in the
+room is to change code until the symptom disappears. That pull is the enemy. A symptom that vanishes
+under a guessed edit usually moved; it rarely died. This skill replaces guess-and-patch with a
+short, evidence-driven loop that ends only when **one confirmed cause** has been named, fixed, and
+proven gone.
+
+The one rule everything else serves: **no fix before a reproduced, isolated, confirmed cause.** If
+you cannot make the bug happen on demand, you cannot know you fixed it — you can only know the
+symptom stopped showing, which is not the same thing.
+
+This is a process skill: it owns the *method*, never the instruments. The test runner, debugger,
+race detector and profiler belong to whichever stack the failure lives in — pull them from the
+delegation table below.
+
+## Model tier — `heavy` (opt-in routing)
+
+This phase's default model tier is **`heavy`** — root-cause diagnosis is deep reasoning. 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 in one line 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.
+
+## Read the room first (register)
+
+Before diagnosing, read `technical_level` in `02-DOCS/wiki/harness/user-profile.md`; it picks
+technical terms or plain words with analogies. With no profile yet, use analogies. The *method*
+never changes with the register — only the words do.
+
+In the `orient` voice, show: the confirmed cause, one line of *why* it produced this symptom, and
+the fix. Ask only what you can't observe yourself (e.g. exact error text). Confirm before a fix that
+changes behavior beyond the bug.
+
+## The loop — five steps, never skipped, never reordered
+
+```text
+REPRODUCE   → make the bug happen on demand. A reliable repro (or a quantified flake rate) is the
+              entry ticket. No repro → you are not debugging yet, you are guessing. Capture the
+              exact command, input, env, and the verbatim error/stack.
+ISOLATE     → binary-search the cause. Halve the surface each step — git bisect across commits,
+              comment/branch to split code paths, remove inputs until the minimal failing case
+              remains. Change ONE variable at a time; note what each change does to the symptom.
+HYPOTHESIZE → from the isolated evidence, state ONE falsifiable cause: "X happens because Y, and if
+              so, changing Z will flip the result." A hypothesis you can't disprove isn't one.
+FIX         → make the smallest change that addresses the *cause* (not the symptom). First, encode
+              the bug as a failing test (it should now go red for the real reason) — then fix until
+              it's green. Treat the test as the proof the cause was real.
+VERIFY      → re-run the repro: symptom gone. Re-run the new test: green. Re-run the surrounding
+              suite: still green (no new red). For a flake, run it enough times to show the rate
+              dropped to zero. Only now is it fixed.
+```
+
+### Reproduce — the entry ticket
+
+A bug you cannot reproduce is not a bug you can fix; it's a rumor. Pin it down:
+
+- The **exact** invocation (command, request, UI steps), the input that triggers it, the environment
+  (OS, versions, env vars, branch/commit), and the **verbatim** error + stack trace — not a
+  paraphrase.
+- For a **flake**, reproduction means a *rate*: run it N times, record `k/N` failures. "Intermittent"
+  is a measurement to take, not a property to accept. A flake almost always means shared state, order
+  dependence, a real race, time/timezone, or network — name which.
+- If you genuinely cannot reproduce, that is the finding. Say so, gather more signal (logs, a failing
+  CI run, the user's exact steps), and do not apply a speculative fix to a bug you can't trigger.
+
+### Isolate — binary-search the surface
+
+The cause is somewhere in a large space; cut it in half, repeatedly, with evidence.
+
+- **Across history:** `git bisect` between a known-good and known-bad commit to land on the exact
+  change that introduced it. Let the repro be the bisect's good/bad oracle.
+- **Across code:** disable/short-circuit half the suspect path; see which half keeps the symptom.
+- **Across inputs/data:** shrink the failing input to the minimal case that still fails.
+- **One variable per step.** Two changes at once and you've learned nothing about either. Write down
+  what each step did to the symptom — the trail *is* the diagnosis.
+
+Delegate the stack-specific tooling (debugger, race detector, profiler, query plan) to the stack
+skill below; `debug` decides *what* to halve, the stack skill provides the instrument.
+
+### Hypothesize → Fix the cause, not the symptom
+
+State the cause as a sentence you could be wrong about, then act on it:
+
+- Fix the **cause**, not the symptom. A `try/except` that swallows the error, a retry that hides a
+  race, a `sleep` that papers over an ordering bug, a bumped timeout — these relocate the symptom and
+  leave the cause armed. If your fix doesn't reference the cause you named, it's a patch on a guess.
+- **Encode the bug as a test first.** The failing test that reproduces the bug is your regression
+  guard; watch it go red for the real reason, then make it green. A fix with no test means the next
+  change can resurrect the bug silently.
+- Keep the change **minimal**. Resist "while I'm here" refactors — they confound the verification and
+  bury the one line that mattered.
+
+### Verify — the symptom and the test, both
+
+The fix is unproven until the original repro no longer fires **and** the new test is green **and**
+the surrounding suite stayed green. For a flake, re-run enough times to show the failure rate is
+zero, not merely lower. Then hand the *whole-gate* re-run (lint/type/full suite/audit) to `verify` —
+that gate, not this skill, is what licenses the word "done".
+
+## Delegating the stack tooling (don't reinvent the instruments)
+
+`debug` owns the loop; the stack skill owns the debugger, the flake mechanics, and the profiler.
+
+| Stack / layer | Where the instruments live | What you pull |
+| --- | --- | --- |
+| FastAPI / async Python | `../fastapi/references/testing.md` | `pytest -x --lf`, `pdb`/`breakpoint()`, async task/race traps, transactional-rollback fixtures to kill state bleed |
+| Go services | `../go/references/testing.md` | `go test -race`, `-run`/`-count=1` to force a flake, `delve`, `pprof`, `errors.Is/As` unwrapping |
+| Next.js / React | `../nextjs/references/testing.md` | Vitest `--no-isolate`/`.only`, Playwright trace viewer, React Server Components vs client boundary errors, hydration mismatches |
+| Flutter / Dart | `../flutter/references/testing.md` | `flutter test --plain-name`, widget pump/settle timing, DevTools, golden diffs |
+| Postgres / data layer | `../postgresdb/SKILL.md` | `EXPLAIN ANALYZE`, isolation-level/locking races, constraint violations, migration-order bugs |
+| Security-shaped failure | `../secure-coding/SKILL.md` | auth/authz edge cases, injection, secret/leak paths surfacing as "weird" failures |
+
+If the failure spans two stacks (a Next.js call into a FastAPI endpoint), reproduce at the boundary
+first — isolate which side actually fails before you open either stack's debugger.
+
+## Log the diagnosis (the 02-DOCS trail)
+
+When the cause is non-obvious — a race, an order dependency, an environment-only failure, a
+regression a reviewer would otherwise have to rediscover — append a short entry to
+`02-DOCS/wiki/sdd/decisions.md` (append-only; create it if absent and add a row to the root
+`CLAUDE.md` `## Knowledge map` under the `sdd/` topic). One entry:
+
+```text
+## YYYY-MM-DD — bug: <symptom in five words>  (feature: <slug>)
+Repro      — the exact command/input that triggered it
+Cause      — the ONE confirmed root cause (not the symptom)
+Fix        — the minimal change + the regression test that guards it
+Why missed — what let it through, so the class of bug doesn't recur
+```
+
+Skip the trivial ones (a typo'd variable). Log the cause a future debugger would pay to know.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails |
+| --- | --- |
+| "I see the likely line — let me just change it and see." | That's guess-and-patch. Reproduce first; a fix to an untriggered bug proves nothing. |
+| "It's intermittent, you can't really reproduce it." | "Intermittent" is a rate to measure (k/N), not an excuse. Flakes have causes: state, order, races, time. |
+| "Wrapping it in try/except makes the error go away." | You hid the symptom and left the cause armed. Fix the cause, not the crash site. |
+| "Adding a sleep/retry/bigger timeout fixes the flake." | It relocates the race. Name the shared state or ordering bug; fix that. |
+| "I'll fix it now and add a test later if there's time." | The bug-reproducing test IS the fix's proof. No red-for-the-right-reason test = unproven fix. |
+| "I changed three things and now it works." | You can't say which mattered or why. One variable per isolate step; revert the rest. |
+| "The repro's gone, ship it." | Gone how? Re-run the repro AND the new test AND the suite. Symptom-absent ≠ cause-dead. |
+| "It works on my machine, so it's fixed." | Environment IS a variable. Reproduce where it actually fails (CI, prod-like) before claiming done. |
+| "This bug is obvious, skip the loop." | Obvious causes are the ones that turn out to be a second bug masking the first. Run the loop. |
+
+## Red flags — stop and re-route
+
+- **The "bug" is a spec contradiction or unclear requirement**, not a defect → route to
+  `clarify` / `analyze`; debugging won't fix an ambiguity.
+- **The fix grows past the cause** (you're refactoring "while you're here") → split it out; keep the
+  fix minimal and verifiable. Improvements go through `implement`.
+- **You're tempted to disable, `skip`, or delete the failing test to make the suite green** → that's
+  the bug winning. Never ship around a red test; diagnose it.
+- **You "fixed" it but can't point to the cause you named** → you patched a symptom. Resume at
+  HYPOTHESIZE.
+- **The cause violates the constitution** (e.g. it only "works" by breaking a quality bar) → surface
+  it; don't smuggle a violation in under the banner of a bugfix.
+
+## Checklist (copy per bug)
+
+```text
+- [ ] REPRODUCE: exact command/input/env + verbatim error captured; repro reliable (or flake rate k/N measured)
+- [ ] ISOLATE: surface halved with evidence (bisect / code split / minimal input); ONE variable per step
+- [ ] HYPOTHESIZE: one falsifiable cause stated ("X because Y; changing Z flips it")
+- [ ] FIX: bug encoded as a failing test (red for the RIGHT reason); smallest change to the CAUSE
+- [ ] VERIFY: repro no longer fires; new test green; surrounding suite still green; flake rate → 0
+- [ ] Non-obvious cause logged to 02-DOCS/wiki/sdd/decisions.md
+- [ ] Handed the whole-gate re-run back to verify; resumed implement where the failure interrupted it
+```
+
+## Where you are in the chain
+
+`debug` is **on-demand**, callable from any phase — most often pulled in mid-`implement` when a test
+fails for a reason you don't understand, or by `verify` when its gate reports a failure it won't
+diagnose. It is not a fixed step in the line `constitution → specify → clarify → plan → tasks →
+analyze → implement → verify → review → ship`.
+
+**Next:** when the one confirmed cause is fixed and proven gone, hand back. Return to `implement` to
+resume the interrupted task, or to `verify` to re-run the full gate and let evidence — not the relief
+of a quiet terminal — declare the work done.

package/skills/shared/debug/evals/README.md

@@ -0,0 +1,88 @@
+# Eval harness — `debug` skill
+
+`debug` is the on-demand ai-hub Spec-Kit **diagnosis discipline**: reproduce → isolate →
+hypothesize → fix → verify, refusing any fix before one root cause is reproduced
+and confirmed. These evals check two things: that it **triggers** when there's a
+real, unexplained failure to diagnose (and stays quiet on near-misses that
+belong to a building/gating/reviewing/clarifying phase), and that it
+**measurably changes the behavior** — turning a flake into a measured rate,
+isolating one variable at a time, fixing the cause not the symptom, and refusing
+to claim "fixed" without a regression test. Cases live in `cases.yaml`. Grading
+is done by an **agent harness** (a Claude Code agent with skills loaded) plus a
+human spot-check, because both routing and "did it actually find the cause
+before patching" are judgment calls — there is no pure shell runner.
+
+## What's in `cases.yaml`
+
+- `should_trigger` — prompts that MUST load `debug` (8 cases, incl. non-obvious
+  phrasings like "it works on my laptop but fails in CI", "the fix didn't stick",
+  and "I can't reproduce it reliably").
+- `should_not_trigger` — near-misses that must route to a real sibling
+  (`route_to`): building a planned feature (`implement`), running the quality
+  gate (`verify`), adversarial diff reading (`review`), resolving a spec
+  ambiguity (`clarify`), cross-checking SDD artifacts (`analyze`). The recurring
+  trap: anything that BUILDS, GATES, READS, or CLARIFIES is not root-cause
+  diagnosis of a confirmed, reproducible defect.
+- `capability` — one end-to-end scenario (an intermittent FastAPI 500 with a
+  "just add a retry" shortcut on offer) with a `must_include` rubric to grade
+  WITH vs WITHOUT the skill.
+
+## Triggering eval
+
+Goal: the skill fires when there's a real, unexplained failure to diagnose, and
+never on a near-miss that belongs to another phase.
+
+1. Configure an agent with the **full catalog of skill descriptions** available
+   for routing (debug + the ai-hub Spec-Kit phases it chains with — implement, verify,
+   review, clarify, analyze, ship — plus the stack/process skills: fastapi, go,
+   nextjs, flutter, postgresdb, secure-coding, deployment, harness, init) so
+   routing competes realistically.
+2. For each `should_trigger` prompt: feed it cold, record whether `debug` is the
+   skill the agent loads. Run **3–5 trials** per prompt (fresh context).
+3. For each `should_not_trigger` prompt: confirm `debug` does NOT load and that
+   the chosen skill matches `route_to`. Same 3–5 trials.
+4. Score: `triggered_correctly / total_trials` across both lists.
+
+**Pass bar: ≥ 90% trigger accuracy** over all prompts and trials, with **zero
+systematic false-positives** on the known traps — "implement task 3 test-first"
+(implement), "run the gate, are we ready to merge" (verify), and "read the diff
+adversarially" (review). A prompt about *building*, *gating*, or *reviewing*
+must not pull in `debug`; only a concrete, unexplained, reproducible failure does.
+
+## Capability eval
+
+Goal: prove the skill changes the answer, not just the routing.
+
+1. For the `capability` scenario, run it **twice**:
+   - **WITHOUT** the skill (base agent, no `debug` loaded).
+   - **WITH** the `debug` skill loaded.
+2. Grade each output against the scenario's `must_include` checklist — one point
+   per checkable item covered. A human or grading agent marks each present /
+   absent.
+3. Compute coverage = `items_covered / total_items` for each run.
+
+**Pass bar: WITH the skill covers ≥ 80% of `must_include`; WITHOUT clearly
+lower** (target a ≥ 30-point gap). The discriminating behaviors are the ones a
+base agent skips: **refusing the retry shortcut** the user offered, turning
+"intermittent" into a **measured k/N rate**, isolating **one variable at a
+time**, encoding the bug as a **test that fails for the right reason** before
+fixing, fixing the **cause not the symptom** (no sleep/retry/timeout bump), and
+re-running until the **flake rate is zero** before handing the gate to `verify`.
+If the base answer already scores ~80%, the case isn't discriminating — tighten
+the rubric.
+
+## Notes on honesty
+
+- Trials are stochastic; report the raw fraction, not a rounded "pass".
+- The highest-signal capability check is the **discipline under pressure**: a
+  correct answer declines the offered retry-patch, reproduces the flake as a
+  rate, and refuses to call it fixed without a regression test that was red for
+  the right reason. Treat a confident "wrapped it in a retry, suite's green now"
+  as a **capability failure** even if it reads smoothly.
+- The skill ships **no `scripts/verify.sh` of its own** — it is a process skill
+  judged on its safety rails (no fix before a confirmed cause, one variable per
+  isolate step, never ship around a red test), not on owning the tooling. It
+  *delegates* the debugger/runner/profiler to the stack skills; eval whether it
+  correctly drives the loop and hands the whole-gate re-run to `verify`.
+- Re-run after any edit to `SKILL.md` — wording changes shift both triggering
+  and rubric coverage.

package/skills/shared/debug/evals/cases.yaml

@@ -0,0 +1,74 @@
+skill: debug
+
+# Prompts that MUST load the `debug` skill. `debug` is the on-demand ai-hub Spec-Kit
+# diagnosis discipline: reproduce -> isolate -> hypothesize -> fix -> verify,
+# refusing any fix before ONE confirmed root cause is reproduced and isolated.
+# It is callable from any phase (most often mid-implement). It does NOT build a
+# planned feature (implement), run the lint/test gate (verify), or read a clean
+# diff adversarially (review).
+should_trigger:
+  - prompt: "This test was green yesterday and now it's red — figure out why before changing anything."
+    why: "A regression with an unknown cause is the loop's entry point: reproduce the red, bisect to the introducing change, then fix the cause — not patch blindly."
+
+  - prompt: "The checkout endpoint throws a 500 sometimes but not always. Track it down."
+    why: "An intermittent failure is a flake to measure (k/N) and a shared-state/race/order cause to isolate — exactly the reproduce->isolate discipline debug owns."
+
+  - prompt: "It works on my laptop but fails in CI. What's going on?"
+    why: "Environment-dependent failure means environment is the variable to isolate; debug reproduces where it actually fails before proposing a cause."
+
+  - prompt: "I added a try/except and the error stopped, but I think the real problem is still there."
+    why: "Swallowing the symptom while the cause survives is the canonical anti-pattern debug exists to correct: find and fix the cause, prove it with a test."
+
+  - prompt: "Our go test -race flags a data race intermittently. Find the root cause and fix it."
+    why: "A flaky race is reproduce-as-a-rate plus isolate-the-shared-state; debug owns the method and pulls the -race/-count mechanics from the go stack skill."
+
+  - prompt: "The fix I shipped last week didn't stick — the bug is back. Why?"
+    why: "A returned bug means the prior change addressed a symptom, not the cause; debug resumes at reproduce and demands a regression test as proof this time."
+
+  - prompt: "Something's wrong with the date calculation but I can't reproduce it reliably."
+    why: "Inability to reproduce is itself the finding; debug's first step is to pin a reliable repro (or measured rate) before any speculative edit — likely a timezone/time cause."
+
+  - prompt: "A test in the FastAPI suite fails for a reason I don't understand. Help me diagnose it, don't just patch it."
+    why: "An unexplained failing test mid-implement is the textbook hand-off into debug's reproduce->isolate->hypothesize loop, delegating pytest/pdb mechanics to fastapi."
+
+# NEAR-MISS prompts that must NOT load `debug`. Each routes to a sibling that
+# exists in this repo. The recurring trap: building, gating, reviewing, or
+# clarifying is NOT root-cause diagnosis of a confirmed defect.
+should_not_trigger:
+  - prompt: "Implement task 3 from the plan: add the /orders endpoint, test-first."
+    route_to: "implement"
+    why: "Building a planned feature with an expected failing test is implement's red->green->refactor; there is no mystery defect to diagnose, so debug does not apply."
+
+  - prompt: "Run lint, type-check and the full suite and tell me if this change is ready to merge."
+    route_to: "verify"
+    why: "Running the whole quality gate to confirm 'done' is verify; it reports failures and hands them to debug, but orchestrating the gate itself is not diagnosis."
+
+  - prompt: "Read this diff adversarially and find design or correctness smells the tests didn't catch."
+    route_to: "review"
+    why: "Adversarially reading a clean, passing diff for latent smells is review; debug starts from a concrete reproduced failure, not a code-reading hunt."
+
+  - prompt: "The spec says 'idempotent' but never defines what duplicate means — resolve the ambiguity."
+    route_to: "clarify"
+    why: "An unclear/contradictory requirement is not a code defect; clarify de-risks the spec. Debugging cannot fix an ambiguity that has no reproducible failure."
+
+  - prompt: "Cross-check the constitution, spec, plan and tasks for contradictions before we write code."
+    route_to: "analyze"
+    why: "Pre-implementation consistency checking across SDD artifacts is analyze; there is no running failure to reproduce, so it is not debug's loop."
+
+# One end-to-end scenario with a rubric to grade WITH vs WITHOUT the skill. A
+# skill-guided answer refuses to fix before reproducing and isolating a single
+# confirmed cause; an ungrounded answer tends to guess-and-patch, paper over a
+# flake with sleep/retry, or claim 'fixed' on a vanished symptom with no test.
+capability:
+  - scenario: "Mid-implement, a FastAPI integration test for the orders endpoint fails intermittently (~3 of 10 runs) with a 500. The user says 'just wrap it in a retry so the suite goes green and we can keep moving'. Diagnose it properly."
+    must_include:
+      - "Reads the register from AGENTS.md (or, absent a profile, notes that and uses analogies) and reports cause, why and fix briefly, while keeping the diagnosis method unchanged by the register."
+      - "REFUSES the retry/wrap-it shortcut: names that a retry relocates the race and leaves the cause armed, so it does not address the root cause."
+      - "REPRODUCE: turns 'intermittent' into a measured rate by running the test N times and recording k/N failures, and captures the verbatim error/stack and exact command."
+      - "Frames the flake as having a real cause class — shared state / test-order dependence / a concurrency race / time / network — and sets out to identify which, not to accept intermittency."
+      - "ISOLATE: binary-searches the surface one variable at a time (e.g. forcing the failing order with the stack's run flags, shrinking to a minimal failing case), delegating the -count/-x/run-flag and async mechanics to the fastapi stack skill rather than reinventing them."
+      - "HYPOTHESIZE: states ONE falsifiable root cause ('X because Y; changing Z flips the result') before touching the fix."
+      - "FIX: encodes the bug as a test that fails for the RIGHT reason first (e.g. a transactional-rollback fixture or deterministic ordering), then makes the smallest change to the CAUSE — not a sleep/retry/timeout bump."
+      - "VERIFY: re-runs the repro until the failure rate is zero (not merely lower), confirms the new test is green and the surrounding suite stayed green, then hands the whole-gate re-run back to verify."
+      - "Produces the non-obvious-cause decision entry for .planning/history.md (appending it where the workspace exists, or delivering the entry inline and noting it would append rather than writing a stray file into an absent tree) and resumes implement at the interrupted task; does not declare 'done' itself."
+      - "Never disables/skips/deletes the failing test to make the suite green, and does not claim 'fixed' on a vanished symptom without a regression test."

package/skills/shared/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: ai-hub
+---
+
+# 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)
+
+Habla con la voz de `orient`: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según `technical_level` en `02-DOCS/wiki/harness/user-profile.md`. Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). **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/shared/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/shared/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."