feat: sync skills to canonical versions, add 11 new skills

skills/contract/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: contract
-description: "Reference convention for sub-agent I/O schemas. Loaded by orchestrator skills via /contract and into agents (e.g., qualify) via the `skills:` field."
+description: "Reference convention for sub-agent I/O schemas. Loaded by orchestrator skills via /contract and into agents via the `skills:` field."
+context: load
 ---
 
 # Contract
@@ -12,9 +13,23 @@ For each sub-agent you plan to dispatch, define a schema before the call:
 - `artifacts` — named structured fields expected back (not freeform prose)
 - `non_goals` — what the sub-agent must NOT do
 - `failure_modes` — how to report blocked or partial work
+- `domain` *(optional)* — the knowledge domain for this task. Guides how research, specification, and verification adapt. Common values: `software`, `research`, `design`, `business` — but any freeform string works (e.g., `healthcare`, `legal`, `education`). When omitted, infer from context: git repo present → `software`; PDFs/papers/citations in working directory → `research`; design files/brand assets → `design`; financial models/strategy docs → `business`. Default fallback: `software`.
 
 Embed the schema at the top of every sub-agent's prompt and require results in that exact shape. Instruct each sub-agent explicitly: "Return ONLY the schema fields. No preamble, no analysis prose, no explanation — begin your response with the first schema field." When sub-agents return, validate field-by-field. If any artifact is missing, malformed, or wrapped in prose, re-dispatch only the failing sub-agent with the gap cited. Merge only schema-valid responses.
 
+Also instruct each sub-agent to stop on non-convergence: if repeated attempts at the same sub-goal stop making progress after a few tries, do not keep retrying — return the best partial result through the schema's designated failure/partial channel (`failure_modes`, or whatever blocked/`unverified` field that agent's schema defines), naming what could not be resolved. Activity is not progress.
+
+## Epistemic confidence
+
+Recommended for all sub-agents. Add to your return schema:
+
+- `confidence` — low / medium / high — how confident is the sub-agent in the completeness and accuracy of its findings?
+- `coverage_gaps` — what the sub-agent couldn't access, verify, or search (e.g., proprietary databases, paywalled sources, unpublished practitioner knowledge, subjective judgment areas)
+- `boundary_flag` — if the sub-agent hit an epistemic boundary, name it: `non-falsifiable` (claim can't be tested), `low-coverage` (search was limited), `tacit-knowledge` (unwritten knowledge required), `unprecedented` (genuinely novel, no baseline), `time-sensitive` (answer depends on current state), or `none`
+- `recommended_action` — what should happen next: `proceed` (findings solid, move ahead), `human-gate` (pause for human judgment before acting), `re-retrieve` (try different search strategy or sources), `elicit` (generate prompts to validate with domain experts)
+
+This is NOT required — skills that don't return it continue to work. But when present, coverage gaps and boundary flags surface automatically during merge, preventing silent failures.
+
 ## Skip if
 
 - Single-agent dispatch

skills/devils-advocate/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: devils-advocate
+description: "Adversarially critique a proposal by generating alternatives. Dispatches 3 parallel critics (pragmatist, paranoid, architect lenses) — each invents one alternative approach — then a synthesis step ranks all 4 options and recommends the top choice. When the proposal was authored by someone other than the agent (inherited plan, someone else's PR, external review), a 4th steelman critic runs in the same parallel wave and strengthens the original first, so it is judged at its strongest rather than its weakest. Use when a plan, fix, scoping, decomposition, or named recommendation will drive decisions and you want structured alternative-generation before committing. Complements /shadow-verify — that skill re-derives factual claims; this one critiques whether the chosen approach itself is best."
+context: load
+---
+
+## Sub-agent contract
+/contract
+
+When a proposal — a plan, fix, decomposition, scoping, or named recommendation — will drive user decisions, file edits, or commits, do NOT act on it as-given. Run a devils-advocate critique wave **before** acting, and use the recommendation as input to the decision.
+
+**Wave 2 — Parallel critics (3 fixed lenses + 1 conditional, independent):**
+1. Extract the **proposal** (the approach being critiqued) and the **goal** (what the proposal is trying to accomplish). Both should be plain prose. Do NOT include the original proposer's reasoning or evidence — critics must invent alternatives without anchoring on the chosen path.
+2. Dispatch 3 critics in parallel. **Default `subagent_type: "research-agent"`** (mechanically locked to Read/Grep/Glob/WebFetch/WebSearch — cannot Edit/Write/commit). Each critic receives ONLY the proposal + goal + ONE lens:
+   - **pragmatist** — cheapest-path. "What is the cheapest approach that solves the goal? Argue why the proposal may be over-engineered."
+   - **paranoid** — safest-path. "What could go wrong with the proposal? Propose a safer alternative with narrower blast radius."
+   - **architect** — right-level. "Is the proposal addressing the right abstraction level? Propose an alternative one level up (systemic fix) or down (targeted fix)."
+3. Each critic returns `{lens, alternative, tradeoff, strength}` where `strength ∈ {weak, medium, strong}` reflects the critic's confidence that its alternative beats the original.
+4. **Conditional 4th critic — steelman.** Fires **only when the proposal is externally-authored**: an inherited plan, someone else's PR, an external review, or third-party text the user pasted in. It does **not** fire on a proposal the agent authored itself this session — there the proposer's reasoning is already in main context and strengthening is a no-op that taxes the hottest call path. When it fires, dispatch it **in the same parallel wave** as the other three (never before them), on the same `research-agent` base, receiving ONLY the proposal + goal + the steelman lens — the closed input set of step 2 is unchanged, and no critic ever sees another critic's output.
+   - **steelman** — strongest-version. "Restate this proposal as its strongest defensible version. Fill in assumptions its author left implicit, supply the evidence that would best support it, and drop claims too weak to defend. Do not critique it and do not propose an alternative."
+5. The steelman returns `{strengthened_original, gaps_filled, weak_claims_dropped}` — deliberately **not** the `{lens, alternative, tradeoff, strength}` shape. It is an annotation on the original, never a competing option, so it does not enter the ranking as a 5th candidate and does not carry a `strength` score.
+
+**Invariant (why steelman sits *inside* Wave 2, not before it):** a steelman is by construction the proposer's reasoning and evidence, reconstructed and amplified — the single most anchoring artifact obtainable. Routing it upstream of the other critics would hand them a hardened target and violate step 1's prohibition, converting invention into rebuttal. Keeping it a peer in the parallel wave preserves critic independence, which is what makes convergence (Wave 3.5) and `dissent` (Wave 3) informative at all. Never promote it to a pre-wave.
+
+**Wave 3 — Synthesis (sequential, single agent):**
+1. Dispatch one synthesis agent (same research-agent base). Input: original proposal + goal + all 3 critic outputs, plus the steelman annotation when Wave 2 produced one.
+2. Rank all 4 options (original + 3 alternatives) along: **cost** (implementation + ongoing), **risk** (blast radius + reversibility), **scope-fit** (how cleanly it solves the stated goal, no more), **goal-fit** (how well it addresses the underlying intent, not just the surface goal). When a steelman annotation is present, score the **original at its strengthened form** — the point is to beat the proposal at its best, not to win against a version its author would disown. The candidate count stays 4: the annotation upgrades how `original` is judged, it does not add an option.
+3. Recommend ONE top choice with a one-paragraph rationale.
+4. Flag `dissent = true` when ≥2 critics returned `strong` alternatives disagreeing with the recommendation — signals the synthesizer is overruling well-argued dissent, so confidence is low. Include a `dissent_note` summarizing the strongest counter-argument.
+
+**Wave 3.5 — Composition-boundary check (fires on convergence):**
+Critics that converge may all have evaluated the proposal in artifact-isolation — none read the boundaries where it composes with siblings. A convergent verdict reached in isolation can be confidently wrong (e.g., critics agree on a UI glyph asserting visual continuity, but none saw that parallel-branch flushes reorder it). When the synthesis recommendation is **convergent** — recommendation ≠ original with ≥2 critics having returned the same alternative — dispatch ONE context-injection verifier (**`subagent_type: "research-agent"`** — Read/Grep/Glob/WebFetch only, no Edit/commit) BEFORE surfacing:
+1. Its job is NOT to re-evaluate the proposal in isolation. It reads the 3 nearest composition boundaries — upstream caller, downstream consumer, and the render/event/state pipeline that interleaves the proposal's target with siblings.
+2. For each boundary: does the recommendation survive when the boundary varies? Check **temporal interleaving** (can flushes / parallel branches / sibling completions reorder it?), **state threading** (does it assume a point-of-use state upstream can break?), **adjacency assumptions** (does it presume render-tree / scrollback / call-graph adjacency that isn't load-bearing under recomposition?).
+3. Returns `CONFIRMED` only if the recommendation survives all three; otherwise `OVERRIDE: <specific boundary condition that breaks it>`. (These verdicts are internal to Wave 3.5 — distinct from shadow-verify's verifier verdict vocabulary.)
+
+Until the verifier returns `CONFIRMED`, the convergent recommendation is a **candidate**, not a recommendation. On `OVERRIDE`, fold the named condition into the matrix and re-rank. **Cap:** if `OVERRIDE` recurs after 2 re-ranks, escalate the full composition failure to the user rather than cycling further — the matrix cannot resolve a boundary violation on its own.
+
+**Scope guard:** skip when the proposal is purely local with no composition surface, or is anchored to an external referent that survives independently of the system. Does not fire when `dissent = true` — that path surfaces the matrix directly; adding a Wave 3.5 gate on already-uncertain output adds friction without signal. Fires once per convergent verdict, not per critic.
+
+**Merge + surface:**
+- Recommendation = `original` → the proposal survived critique; proceed with it. **With a steelman annotation present, the strengthened form is what survived and is therefore what you proceed with** — it is the artifact Wave 3 actually scored, and executing the verbatim text instead would run a version that never won: one that can omit a prerequisite the steelman made explicit, or reinstate a claim it dropped as indefensible. Rank and execute must name the same artifact. Surface it **as** the strengthened version, with `gaps_filled` (assumptions the proposal depends on but never stated) and `weak_claims_dropped` (claims too weak to defend) shown as an explicit delta against what the user wrote, so they can see exactly what changed and reject it if they disagree. The substitution must be **visible, never silent** — do not present strengthened text as if it were the user's verbatim proposal. With no steelman annotation, `original` is the verbatim proposal and proceeds unchanged.
+- Recommendation ≠ `original`, `dissent = false`, ≥2 critics returned the same alternative → convergent path: run Wave 3.5, then surface the alternative with rationale (on `OVERRIDE`, re-rank first) before acting.
+- Recommendation ≠ `original`, `dissent = false`, only 1 critic backed the winner → no convergence to guard: surface the alternative with rationale directly (Wave 3.5 does not fire).
+- `dissent = true` → present the matrix to the user; do not act. Confidence is low.
+
+**When to invoke:**
+Any time a proposal, plan, root-cause + fix, decomposition, or named recommendation will drive user decisions, file edits, commits, or external side-effects. Especially useful when the proposal "feels right" — that's when alternative-generation has the highest value.
+
+**Skip when:**
+- Single-line edits or trivial fixes where alternative space is empty.
+- User explicitly named the chosen approach by name (critiquing a directly-requested action is friction, not signal).
+- An upstream orchestrator already produced comparative output on the same claim-space (`/diagnose`'s hypothesis ranking does not need a second opinion on its hypotheses — though the *final fix* it produces can still benefit).
+- The **steelman critic specifically** no-ops when the agent authored the proposal itself this session — the common plan-mode path ("form a candidate plan → apply adversarial pressure"). The other three lenses still run; only the 4th is skipped. Strengthening your own just-written plan restates context you already hold.
+
+## Appendix: lens selection (non-binding)
+
+Three fixed adversarial lenses always run, plus the conditional steelman; domain-specific lens packs (software-perf, research-methodology, business-risk) are V2 work. When the proposal's domain is clear, the synthesis agent may weight dimensions accordingly — but the critic lenses themselves remain fixed.
+
+| Lens | Typical alternatives it surfaces |
+|------|----------------------------------|
+| pragmatist | narrower scope, simpler implementation, reuse-over-build |
+| paranoid | smaller blast radius, reversibility, guardrails, staged rollout |
+| architect | systemic fix one level up, targeted fix one level down, different subsystem ownership |
+| steelman *(conditional)* | no alternative — returns the original at its strongest, plus the unstated assumptions it depends on and the weak claims worth dropping |
+
+Note that the three adversarial lenses are all oppositional: each asks some form of "what would be better?" The steelman is the only lens that moves the other way, which is why it returns a different shape and is scored differently. If a future lens pack adds more stances, check which direction each one points before assuming it can reuse the `{alternative, tradeoff, strength}` contract.

skills/diagnose/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: diagnose
+description: "Parallel root-cause analysis for bugs and failing tests. Use when a test fails, a bug is reported, or behavior is unexplained — dispatches sub-agents to form and validate hypotheses in isolated worktrees."
+context: fork
+---
+
+Gather context: read the failing test or bug description, relevant error output, and recent git changes. If no failing test exists yet, write a minimal reproducer test (or identify a concrete verification command) before proceeding — hypotheses need a pass/fail signal to validate against. Dispatch two sub-agents in parallel — one to search the codebase for code paths involved in the failure (`subagent_type: research-agent`, read-only), and one to check recent commits and diffs that could have introduced the regression (`subagent_type: general-purpose` — requires Bash for `git log`/`git diff`/`git show`). When both return, synthesize findings into 2–4 ranked hypotheses, each with a specific code location and proposed cause.
+
+For each hypothesis, dispatch a sub-agent with `isolation: "worktree"` to apply a minimal speculative fix, run the test or verification command, and then run the broader related test suite to check for regressions. Run all hypothesis-testing agents in parallel. Collect results: which fixes passed, which didn't, and any regressions surfaced by the broader suite.
+
+Report the validated root cause (the hypothesis whose fix passed), the speculative fix diff, and regression status from the broader test run. If no hypothesis passes, synthesize what was learned and form a second round of hypotheses. If the user approves the fix, apply it to the main worktree.