@dennisrongo/skills 0.6.0 → 0.7.0

package/README.md

@@ -107,6 +107,7 @@ node bin/claude-skills.js list
 | [`sql-review`](./skills/sql-review/SKILL.md) | Pre-commit SQL code review for uncommitted `.sql` changes (staged + unstaged). Detects 17 antipattern classes that map to **real production incident causes** — `sp_send_dbmail` in CATCH blocks (masks the real exception as a misleading permission denial), broken retry patterns (`@retry` declared without a surrounding `WHILE` loop), swallowing CATCH blocks (no `THROW`/`RAISERROR`/log), **new tables created without a primary key or any index** (the silent perf-then-deadlock killer), parameter-vs-column type mismatches (8152 truncation risk), `EXEC()` string concatenation without `sp_executesql` parameters (SQL injection), `NOLOCK` inside transactional write paths, `UPDATE`/`DELETE` without `WHERE`, cursors without `READ_ONLY FORWARD_ONLY LOCAL`, hardcoded environment values (emails, server names, paths, linked servers), cross-DB references like `msdb.dbo.*`, missing `SET NOCOUNT ON`, missing `GRANT EXECUTE` on `CREATE PROC`, `BEGIN TRANSACTION` outside `TRY`/`CATCH` with `XACT_STATE` handling, and vestigial control-flow comments hinting at refactor leftovers (e.g. `-- end while loop` with no `WHILE`). **Scope-aware** — full-file scan for new files, diff-only scan for modified files so legacy antipatterns in untouched parts of a large SP don't flood the report. Categorizes findings as `BLOCKER` / `WARN` / `INFO` with `file:line` citations and per-finding fix recommendations. **Never edits SQL unprompted** — produces the report, then asks per fix. Distinct from [`code-review`](./skills/code-review/SKILL.md), which carries the general best-practice catalog without SQL-specific patterns. Triggers on `/sql-review`, "review my SQL", "review the SQL diff", "lint the SQL", "check my SQL changes", "SQL pre-commit check", or "audit my stored proc". |
 | [`task-executor`](./skills/task-executor/SKILL.md) | Disciplined execution loop for a single, already-defined task — Understand → Inspect → Plan → Execute incrementally → Validate after every change → Track assumptions → Update progress. Forces a strict per-turn output format with six fixed sections (**Goal** / **Current understanding** / **Files to inspect** / **Plan** / **Progress** / **Risks** / **Assumptions**) so the work stays legible and resumable instead of devolving into ad-hoc edits across turns. When the inspection working set spans multiple layers (controller + service + persistence + tests), Phase 2 convenes an **inspection council**: parallel `Explore` sub-agents — one per layer slice — each map their area and return `file:line`-cited findings on existing patterns, wiring points, and sibling test classes; the main session aggregates the results into `Current understanding` so the working context window stays free for the strict per-turn output the executional phase keeps emitting. Small inspection sets (≤ ~5 files, one layer) skip the council and read inline. Enters Plan Mode after inspection and gates on `ExitPlanMode` approval before writing any code; every plan step is then one logical change followed by an immediate validation (test, build, type-check, curl, page load) before the next checkbox ticks. Assumptions are tracked explicitly until confirmed by code or the user — and promoted into `Current understanding` or killed, never silently carried. Composes downward from [`plan-and-build`](./skills/plan-and-build/SKILL.md) (which interviews the user to design the feature) and routes back to it when the user invokes this skill on a fuzzy spec. Triggers on `/task-executor`, "Work on task: …", or any concrete, already-defined task handed to Claude for execution. |
 | [`tauri-2-app`](./skills/tauri-2-app/SKILL.md) | Scaffold a new Tauri 2 desktop app (Rust backend + TypeScript/React frontend) using a thin-frontend / rich-Rust-backend architecture with modular `commands/`, `state/`, `storage/`, `platform/` traits, `error/` macros, single-instance + updater plugins wired correctly, capability JSON per window, encrypted secrets at rest, `spawn_blocking` for sync work, and typed frontend command hooks — while forbidding common pitfalls (committed `.backup`/`.orig`/`.temp` files, plaintext API keys in `settings.json`, tokens in `localStorage`, `cfg!(target_os)` in command bodies instead of trait-based platform code, hand-rolled date math instead of `chrono`, raw `std::fs` bypassing capability checks, blocking I/O inside async commands, missing `windows_subsystem = "windows"` in `main.rs`, `devtools: true` in release, hardcoded bundle identifiers / updater pubkeys / CDN URLs). Three modes — full project scaffold, add-a-command end-to-end, add-a-Rust-module slice. Resolves Cargo + npm versions at scaffold time (not hard-coded). |
+| [`think-like-fable`](./skills/think-like-fable/SKILL.md) | An operating manual for rigorous reasoning, written as a senior operator handing their craft to a sharp junior — applied to whatever task is at hand rather than replacing it. Eight disciplines, each with the procedure, a worked example, and the failure it prevents: read the need behind the literal ask, decompose into **independently checkable** pieces, spend effort where the risk lives (not where the work is easy or interesting), verify load-bearing claims by **re-deriving** them instead of recognizing them ("a claim about code you haven't opened is a hypothesis"), tag every claim **verified / inferred / assumed** in the text, attack your own conclusion before handing it over, and communicate answer → reasoning → risk in that order. Names the seven mistakes that look like competence and aren't (thoroughness theater, fluent overclaiming, premature agreement, complexity as signal, silent scope repair, momentum completion, deference to your own prior output) and ends with a five-question self-test to run on every answer before sending. Triggers on "think like fable", "/think-like-fable", "be rigorous", "are you sure?", "don't guess", or any high-stakes analysis where a confident wrong answer is worse than a slow right one. |
 | [`write-a-skill`](./skills/write-a-skill/SKILL.md) | Author a new Claude Code skill — interview-driven scaffolding that produces a properly-structured `SKILL.md` (trigger-rich YAML description, "When to use", workflow, examples, anti-patterns), drops it in the right location (library `skills/`, project `./.claude/skills/`, or global `~/.claude/skills/`), updates the README skills table when extending this library, and runs a review checklist focused on the failure mode that matters most — under-triggering descriptions. Triggers on "create/write/add a skill", "/write-a-skill", or a pasted SKILL.md URL with "one like this". |
 
 Run `skills list` to see this list with install status, or browse [`skills/`](./skills) directly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dennisrongo/skills",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "A curated, fine-tunable library of Claude Code skills. Install globally or per-project via npx.",
   "bin": {
     "skills": "bin/claude-skills.js"

package/skills/_template/SKILL.md

@@ -32,3 +32,11 @@ Step-by-step guidance for Claude on how to handle the task.
 ## Notes
 
 Any caveats, edge cases, or things to watch out for.
+
+<!-- Author reminders (delete before shipping):
+- Description carries 3+ concrete trigger phrases — it's the only field Claude reads to decide.
+- Give every rule that matters a ❌/✅ pair (same output done badly, then well).
+- Any assertion the skill asks for needs an evidence gate — name the check that licenses it.
+- Report-producing skills: state "zero findings is a valid outcome".
+-->
+

package/skills/code-review/SKILL.md

@@ -22,6 +22,16 @@ If you find issues, **do not start editing**. Produce the findings report first.
 
 This rule overrides any general "be helpful, fix it" instinct. A drive-by refactor mid-review collapses the user's mental model of what changed.
 
+## Evidence rules
+
+A claim about code you haven't opened this session is a hypothesis — verify it or label it as one.
+
+- **Read beyond the hunk.** Before flagging anything, `Read` the full enclosing function — and the whole file when it's small. Most false "missing null check" / "unhandled error" findings dissolve when you see the guard 10 lines above the hunk, or the caller that validates. A finding based only on diff-hunk context is not reportable.
+- **Grep before claiming absence.** "Dead code", "unused", "never called", "duplicated elsewhere" each require a repo-wide `Grep` for the identifier first. Cite the search in the finding: *"no callers found (`grep -rn 'buildQuery' src/`)"*.
+- **Quote, don't paraphrase.** Failing test output, error messages, and load-bearing identifiers go into findings verbatim (trimmed). A paraphrased error message loses the exact token that matters.
+- **Zero findings is a valid outcome.** Never invent findings to appear thorough — thoroughness is measured by what you checked, and the report already lists that (build, tests, lenses run). An empty Blockers section with a green build is a good report.
+- **User framing is input, not conclusion.** "The auth part is fine, just check the parser" does not exempt the auth part. Weight attention toward the ask, but never skip a category on the user's say-so.
+
 ## Workflow
 
 1. **Snapshot the diff.** Run in parallel:
@@ -38,7 +48,7 @@ This rule overrides any general "be helpful, fix it" instinct. A drive-by refact
    - `Cargo.toml` → `cargo build`, `cargo test`
    - `Makefile` → check for `test` / `build` targets first
    - Monorepo (`turbo.json`, `nx.json`, `pnpm-workspace.yaml`) → use the orchestrator
-4. **Run tests, then build.** Tests first (faster signal). If tests pass, run the build. Capture output. If a command doesn't exist or fails to start, note it and continue — don't fabricate a green result.
+4. **Run tests, then build.** Tests first (faster signal). If tests pass, run the build. Capture output. If a command doesn't exist or fails to start, note it and continue — don't fabricate a green result. A result you didn't observe is **not run** (report ⚠️ not detected), never "passed".
 5. **Review.** Decide single-pass vs. lens council (see [Lens council](#lens-council-for-non-trivial-diffs)):
    - **Single-pass (inline)** when the diff is small and tightly scoped — roughly: < 100 lines changed, < 5 files, no security-sensitive paths (auth, crypto, input validation, file/SQL/shell sinks). Walk the priority list yourself; faster on trivial changes.
    - **Lens council** otherwise. Spawn parallel `Explore` sub-agents — one per lens — then run an adversarial critique round before reporting.
@@ -59,13 +69,20 @@ These rules govern the fix-application phase only — they don't change the repo
 
 ## Categories
 
-- **`blocking`** — must fix before ship: bug, broken contract, security hole, build/test failure, missing migration, hard-coded secret.
+- **`blocking`** — must fix before ship: bug, broken contract, security hole, build/test failure, missing migration, hard-coded secret. **Burden of proof:** a `blocking` finding must include a one-sentence concrete failure scenario (*this input/state → this wrong outcome*). If you cannot write that sentence, demote to `suggestion`.
 - **`suggestion`** — would improve the code; user can take or leave. DRY consolidations, dead-code removal, missing error handling on non-critical paths.
 - **`nit`** — style/preference; never blocks.
-- **`praise`** — something done well. Include at least one when there's something genuine to praise.
+- **`praise`** — something done well, cited to a specific `file:line` (*"the retry wrapper at `http.ts:40` is exactly right for this flaky API"*). Generic filler ("nice clean code!") is worse than omitting the section. Include one only when it's genuine.
 
 Lead each finding with the *why*. "This swallows the exception so a failure here is silently lost" beats "add error handling".
 
+Same finding, written badly and well:
+
+- ❌ **B1. Add error handling to `fetchUser`** — `api/user.ts:42`. *(No failure scenario, no consequence, one citation — reads as a reflex; the reviewer can't verify it or weigh it.)*
+- ✅ **B1. Unhandled rejection on deleted user** — `api/user.ts:42`. **Why:** `fetchUser` rejects on 404, but `ProfilePage` (`pages/profile.tsx:18`) never catches — visiting a deleted user's profile renders a blank page with an unhandled rejection. **Fix:** catch in `ProfilePage` and render the not-found state.
+
+The ✅ names the trigger, the concrete consequence, and both `file:line` sites — verifiable without re-deriving it.
+
 ## What to look for
 
 Priority order — review top-to-bottom, stop wasting tokens on lower categories once a higher one is on fire.
@@ -162,7 +179,7 @@ Performance (§5), readability (§7), and style (§8) usually roll into Design
 1. **Spawn in parallel.** Send a **single message** with N `Agent` calls (`subagent_type=Explore`). Each lens gets:
    - The full diff (or the slice relevant to its files when the diff is huge).
    - **One** lens with its checklist verbatim from [What to look for](#what-to-look-for).
-   - Instructions: "Find issues **only in your lens.** Categorize each as `blocking` / `suggestion` / `nit`. Cite `file:line` for every finding. Lead each finding with the *why*. If your lens has no findings, say 'no findings' explicitly. Report in ≤500 words."
+   - Instructions: "Find issues **only in your lens.** Read the full enclosing function before flagging — hunk-only findings are not reportable. Categorize each as `blocking` / `suggestion` / `nit`; a `blocking` must state a one-sentence concrete failure scenario. Cite `file:line` for every finding. Lead each finding with the *why*. If your lens has no findings, say 'no findings' explicitly — do not pad. Report in ≤500 words."
 2. **Collect findings.** Each agent returns its list. Don't publish yet.
 3. **Critique round.** Read all lenses side by side, then do an adversarial pass before the report:
    - **Challenge every `blocking`** — "is this actually exploitable / actually a bug / would this actually break in production?" Demote to `suggestion` or drop if the answer is no when you read the surrounding code.
@@ -257,6 +274,10 @@ End with the offer. Wait for the user's choice. Apply only the approved set, the
 - ❌ DRY-ing prematurely — calling out three similar lines as duplication when the right call is to leave them. Note the pattern; flag only when the abstraction is clearly warranted.
 - ❌ Padding the report with style nits when there are correctness blockers.
 - ❌ Hand-wavy findings without `file:line`.
+- ❌ Flagging from the diff hunk alone. Read the enclosing function first — the guard is often 10 lines above the hunk.
+- ❌ Claiming "unused" / "dead" / "duplicated elsewhere" without a repo-wide grep for the identifier.
+- ❌ A `blocking` with no concrete failure scenario. Can't write "this input → this wrong outcome"? It's a `suggestion`.
+- ❌ Inventing findings on a clean diff to look thorough. Zero findings + green build is a valid, complete report.
 - ❌ Convening the lens council on a 15-line diff. Single-pass it.
 - ❌ Spawning the lens agents serially instead of in parallel — one message, N agents.
 - ❌ Skipping the critique round and publishing the raw union of lens findings. False-positive blockers erode trust fast.

package/skills/codebase-explainer/SKILL.md

@@ -41,21 +41,25 @@ If an `ONBOARDING.md` already exists, this is **refresh mode**: read it first, t
 Spawn `subagent_type=Explore` calls in a **single message** so they run concurrently. Brief each agent self-containedly — it has no conversation context. Default fan-out:
 
 - **System overview** — what this project actually does, key domains, top-level modules, public-facing surfaces (HTTP routes / CLI commands / exported APIs).
-- **Dependency map** — top-level prod deps only (skip dev/test/types). For each: what it does *in this codebase* (not generic), and the load-bearing call site (`file:line`). If a dep is genuinely non-obvious (niche library, internal fork, name that doesn't reveal its purpose), the agent MAY check `context7` (or any docs-MCP server available in the environment) for a one-line "what is this library" — `context7__resolve-library-id` → `context7__query-docs`. Skip the lookup for well-known libraries (React, Express, Prisma, etc.) — the *generic* description is what we're trying to avoid; what matters is how it's used *here*.
+- **Dependency map** — top-level prod deps only (skip dev/test/types). For each: what it does *in this codebase* (not generic), and the load-bearing call site (`file:line`). If a dep is genuinely non-obvious (niche library, internal fork, name that doesn't reveal its purpose), the agent MAY check `context7` (or any docs-MCP server available in the environment) for a one-line "what is this library" — `context7__resolve-library-id` → `context7__query-docs`. Skip the lookup for well-known libraries (React, Express, Prisma, etc.) — the *generic* description is what we're trying to avoid; what matters is how it's used *here*. The "how it's used here" line requires a call site the agent actually opened. If no call site is found, the row reads **"declared but no usage found"** — that's a finding (candidate for removal), not a gap to paper over with a guess from the package name.
 - **Startup flow** — entry point → bootstrap → config loading → server start. A numbered sequence with `file:line` per step.
-- **Auth flow** — login/session/token handling, middleware/guards, user model, where authorization decisions are made. If none, the agent must say "no auth detected" explicitly so Step 3 doesn't fabricate one.
-- **Important files** — the 5–15 files a new contributor *must* know about, each with a one-line "why it matters."
+- **Auth flow** — login/session/token handling, middleware/guards, user model, where authorization decisions are made. This section must be a **traced code path** — a middleware/guard/session check the agent read this session, cited `file:line` — never an inference from an auth library appearing in the manifest. If none, the agent must say "no auth detected" explicitly AND state what was searched (e.g. "grepped for middleware, `session`, `jwt`, `[Authorize]`, guards — no hits") so Step 3 doesn't fabricate one.
+- **Important files** — the 5–15 files a new contributor *must* know about, each with a one-line "why it matters." A file earns its slot by being load-bearing, and the agent names the evidence per file: imported widely (roughly how many importers), owns a core domain concept, or is an entry point. "Looks important" is not evidence.
 
 Each agent reports back in ≤300 words with `file:line` citations. Don't ask Explore to read entire files — ask for the specific answer plus citations.
 
 ### 3. Synthesize ONBOARDING.md
 
-Write the artifact to `docs/ONBOARDING.md` if a `docs/` directory exists, otherwise `ONBOARDING.md` at repo root. Sections, in this order:
+Write the artifact to `docs/ONBOARDING.md` if a `docs/` directory exists, otherwise `ONBOARDING.md` at repo root.
+
+**No-fabrication gate:** every claim in the file traces to a probe run this session — a file an agent read, a grep it ran. If a claim can't name its probe, it's a hypothesis: verify it or omit it. Never fill a section by inference from framework conventions ("Next.js apps usually…").
+
+Sections, in this order:
 
 1. **Read this first** — 3–7 bullets max. The minimum a fresh contributor needs to not be dangerous.
 2. **System overview** — 1–3 paragraphs. What it does, who it serves, the dominant architectural shape.
 3. **Startup flow** — numbered, with `file:line` per step.
-4. **Auth flow** — same shape, or a one-liner "No authentication layer — this is X" if the agent confirmed none.
+4. **Auth flow** — same shape, or a one-liner "No authentication layer — this is X (searched: middleware, session/token handling, guards)" if the agent confirmed none.
 5. **Dependency map** — table: `Dependency | What it does here | Key call site`.
 6. **Important files** — bulleted list with `file:line` and a one-line "why it matters."
 7. **Project glossary** *(optional)* — only if `CONTEXT.md` exists or domain terms surfaced repeatedly during exploration.
@@ -97,7 +101,10 @@ If making this teammate-accessible would help, mention `ShareOnboardingGuide`
 - ❌ Generic framework descriptions ("This is a Next.js app."). Call out what makes THIS codebase non-obvious — the custom session helper, the funky background job runner, the legacy module that traps newcomers.
 - ❌ Listing every dependency including dev/test/types. Prod + top-level only.
 - ❌ "Important files" with 40 entries. 5–15 is the budget. If you can't pick, you don't understand the codebase yet — Explore more.
-- ❌ Inventing an auth flow when there isn't one. If the agent reports no auth, the section says "No authentication layer." That's load-bearing information for a future reader.
+- ❌ Inventing an auth flow when there isn't one. If the agent reports no auth, the section says "No authentication layer" plus what was searched. That's load-bearing information for a future reader.
+- ❌ Auth described from the manifest instead of the code. ❌ "Uses NextAuth for authentication" because `next-auth` sits in `package.json` vs. ✅ "Requests hit `middleware.ts:8` → `auth()` from `lib/auth.ts:12`; unauthenticated users redirect at `middleware.ts:19`." Trace the path or write "none detected (searched: …)".
+- ❌ Papering over a dependency with no found call site. "Declared but no usage found" goes in the table verbatim — it's a finding.
+- ❌ Important files picked by vibes. Each entry names its evidence: import count, domain concept owned, or entry-point role.
 - ❌ Reading whole source files into the main context. Sub-agents return summaries with `file:line` citations — trust them.
 - ❌ Claims without `file:line` citations. A claim the next reader can't verify rots fast.
 - ❌ Hard-coded dates ("as of November 2025") in the file body. Git history is the timestamp.

package/skills/conventional-commits/SKILL.md

@@ -46,7 +46,7 @@ Before composing the message, gather two pieces of context from the repo.
 1. Run `git rev-parse --abbrev-ref HEAD` to get the current branch name.
 2. Take the last `/`-separated segment of the branch (so `feature/12345-fix_this_bug` becomes `12345-fix_this_bug`).
 3. If that segment starts with one or more digits followed by `-`, `_`, or end-of-string, those leading digits are the ticket number.
-4. If no leading numeric ID is found, **omit `#<ticket>` from the message entirely** — do not invent one and do not prompt the user for it.
+4. If no leading numeric ID is found, **omit `#<ticket>` from the message entirely** — do not invent one, do not guess one from conversation context, do not reuse a stale number mentioned earlier in the session, and do not prompt the user for it. The branch name is the only source of truth for the ticket.
 
 Examples:
 
@@ -81,6 +81,11 @@ How to decide:
 3. Breaking changes get a `!` after the type / scope (e.g., `#12345 (API) feat!: drop support for Node 16`) and a `BREAKING CHANGE:` footer.
 4. Inner `type(scope)` is optional and usually redundant once `(PROJECT)` is present. Only use it when it adds real specificity beyond the project tag (e.g., `#12345 (API) fix(auth): ...` when "auth" narrows further than "API").
 5. Body explains the *why*, not the *what*. Wrap at 72 chars.
+6. The description states **what changed** at the level a reader scanning a changelog needs; the *why* goes in the body. A description that only restates the type ("fix bug") carries no information — rewrite it.
+   - ❌ `fix: fix bug in login`
+   - ✅ `fix: reject expired refresh tokens instead of issuing new access tokens`
+7. The type must match the **diff**, not the user's phrasing. The user saying "quick fix" while the staged diff adds a new endpoint means `feat`, not `fix`. Determine the type from `git diff --staged` output you actually read this session — never from the conversation summary or the user's wording alone.
+8. If the staged diff contains two unrelated changes (e.g., an auth bug fix plus a new export page), say so and suggest splitting into two commits — do not paper over it with a vague umbrella description like `chore: various updates`.
 
 ## Workflow
 
@@ -89,7 +94,7 @@ When the user asks for a commit message:
 1. Get the current branch with `git rev-parse --abbrev-ref HEAD` and extract the ticket number per the rules above.
 2. Inspect the staged diff: `git diff --cached` (or `git diff` if nothing is staged).
 3. From the changed file paths, determine the project tag — or decide to omit it.
-4. Categorize the change into one of the types.
+4. Categorize the change into one of the types — based on the diff you just read, not on how the user described the work.
 5. Write a concise description.
 6. If the change is non-trivial, add a body explaining the rationale.
 7. Flag breaking changes explicitly.
@@ -131,6 +136,8 @@ BREAKING CHANGE: clients reading `user.email` must update to `user.email_address
 - ❌ `Fix: Bug in login page.` (capitalized, trailing period)
 - ❌ `feat: added the ability to export CSV files` (past tense)
 - ❌ `#12345 (CLIENT) feat: added export.` (past tense + trailing period)
-- ❌ Inventing a ticket number when the branch doesn't have one
+- ❌ Inventing a ticket number when the branch doesn't have one — or guessing one from conversation context
+- ❌ `fix: quick fix per request` when the staged diff adds a new endpoint (type from the user's phrasing, not the diff — should be `feat`)
+- ❌ `chore: various updates` covering two unrelated changes — flag the split instead
 - ❌ Forcing a `(PROJECT)` tag when the diff doesn't actually map to API / CLIENT / CONSOLE / DB
 - ✅ `#12345 (CLIENT) feat: add CSV export`

package/skills/diagnose/SKILL.md

@@ -70,6 +70,11 @@ Confirm:
 - [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
 - [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
 
+**Quote error text verbatim — never paraphrase.** The load-bearing token is usually the exact column name, status code, or line number, and paraphrase loses it. The difference between what the error says and what you remember it saying is where diagnosis dies.
+
+- ❌ "some kind of null error in the billing code"
+- ✅ `NullReferenceException at BillingService.cs:84 in HandleSubscriptionEvent` — the `:84` is what distinguishes hypothesis 2 from hypothesis 4.
+
 Do not proceed until you reproduce the bug.
 
 ## Phase 3 — Hypothesise
@@ -82,6 +87,22 @@ Each hypothesis must be **falsifiable**: state the prediction it makes.
 
 If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
 
+**Evidence gate.** A claim about code you haven't opened this session is a hypothesis, not evidence. Cite `file:line` only for lines you actually read; "X is never called" only after you grepped for callers. Label everything else as unverified.
+
+### Mundane first
+
+Exotic hypotheses (framework bug, compiler bug, race condition) are almost always wrong. Before ranking any of them above a boring cause, eliminate the boring ones — each is a 30-second check:
+
+- **Is the code you're reading the code that's running?** Stale build artifact, uncompiled change, cached bundle, old container image. Add a marker log and confirm it appears in the output.
+- **Right branch, right env, right database?** Check `git branch`, the connection string, the env vars actually loaded.
+- **Did the input actually reach the function?** Log at the entry point before theorising about the logic inside.
+- **Typo / off-by-one / wrong variable** in the most recently changed lines (`git diff`).
+- **Config not loaded** — the setting exists but the process never read it.
+
+When the behavior makes no sense, you are looking at the wrong code, the wrong process, or the wrong environment — not at an exotic bug.
+
+**The user's diagnosis is hypothesis #1, not the conclusion.** If the user says "it's probably the cache layer" or "should be a quick fix", rank it, state its falsifiable prediction, and test it like the others. Never skip falsification because the user sounded sure — confident framing is not evidence.
+
 ### Decision gate: inline vs. hypothesis council
 
 - **Inline (skip the council)** when the cause is obvious from one read: a typo in the diff that introduced the bug, a one-file change with a clear root cause, a trivial null/undefined at an obvious site. Form 1–2 hypotheses directly.
@@ -123,8 +144,14 @@ Tool preference:
 
 **Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
 
+**When a probe command fails:** read the full error output — don't skim it. Change exactly one thing based on what it says, retry once. Two failures on the same probe = stop and report; never retry verbatim, never proceed as if it ran, never report an observation you didn't see.
+
+**Stop-digging rule.** After ~3 probe cycles that neither confirm nor falsify the leading hypothesis, stop probing it. Go back to Phase 3 with the evidence gathered so far and re-rank — probes that keep coming back ambiguous usually mean the hypothesis is wrong, not that it needs one more probe. Tunneling on hypothesis #1 is the failure mode this rule breaks.
+
 ## Phase 5 — Fix + regression test
 
+**The accepted hypothesis must explain EVERY observed symptom.** A hypothesis that explains 2 of 3 symptoms is a different bug or an incomplete cause. Before writing the fix, walk the symptom list from Phase 2 and check each one off against the hypothesis — an unexplained symptom means back to Phase 3, not "probably unrelated".
+
 **Minimal comments.** Default to no comments in the fix or the regression test. Add one only when the *why* is non-obvious — a workaround for a specific upstream bug (with a link), a subtle invariant the code relies on, a domain rule that isn't visible from the names. Never write block headers, never restate *what* the next line does, never leave `// TODO` without an issue link. One short line max — no multi-line comment blocks. Names carry the *what*; comments earn their place only when they carry *why*.
 
 Write the regression test **before the fix** — but only if there is a **correct seam** for it.
@@ -157,6 +184,10 @@ Required before declaring done:
 
 - Jumping to a fix before building a feedback loop — you're guessing, not diagnosing.
 - A single hypothesis becomes "the cause" without falsification — anchoring.
+- Adopting the user's "it's probably X" as fact. It's hypothesis #1 — rank it and falsify it like the rest.
+- Ranking a race condition or framework bug above "stale build" before checking the boring causes.
+- Citing `file:line` for code never opened this session, or asserting "never called" without grepping.
+- Accepting a hypothesis that explains most symptoms. Most is not all; the remainder is a different bug or the real cause.
 - Running the hypothesis council for a one-line typo bug. Ceremony for its own sake. Inline 1–2 hypotheses is fine when the cause is staring at you.
 - Spawning defender sub-agents serially instead of in parallel — one message, N agents.
 - A defender that returns "could not find supporting evidence" gets ranked anyway. If the code doesn't back the hypothesis, drop it.

package/skills/dotnet-onion-api/SKILL.md

@@ -42,6 +42,17 @@ The user explicitly does **not** want a hard-coded `<TargetFramework>` baked int
 3. If unsure which is the current LTS, fetch the latest .NET support policy via context7 (`mcp__plugin_context7_context7__resolve-library-id` → `query-docs` for ".NET release schedule" / "dotnet support policy") or WebFetch `https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core`. Quote the version you picked back to the user before generating.
 4. Pin EF Core, ASP.NET Core, and `Microsoft.Extensions.*` package versions to the **latest stable for that TFM** — look them up via context7 (`Microsoft.EntityFrameworkCore`, `Microsoft.AspNetCore.Authentication.JwtBearer`, etc.) rather than guessing. Never hand-paste a version you don't have a source for.
 5. State the chosen TFM and package versions in your reply before writing files, so the user can object before scaffolding.
+6. Concrete resolution commands when context7 is unavailable: `dotnet package search <PackageId> --take 1` or WebFetch `https://api.nuget.org/v3-flatcontainer/<package-id-lowercase>/index.json` (last non-preview entry = latest stable). Never write a version string you did not just resolve this session — no versions from memory, no wildcards, no invented numbers.
+
+**API-drift guard.** The version you resolved in this step decides the API shape — training-data memory is the least trustworthy source in this workflow. Highest-risk hallucination zones:
+
+- EF Core APIs across majors (e.g. `HasCheckConstraint` moved into `ToTable(t => t.HasCheckConstraint(...))` in EF7; query/interceptor APIs get renamed between majors).
+- Hosted-service and `Host` builder idioms — `Host.CreateApplicationBuilder` (post-.NET 7) vs the older `CreateDefaultBuilder` callback style; don't mix the two.
+- TFM defaults: newer TFMs flip `<Nullable>` / `<ImplicitUsings>` behavior — templates must match the resolved TFM, not a remembered one.
+- OpenAPI/Swagger: .NET 9+ templates dropped Swashbuckle for built-in `Microsoft.AspNetCore.OpenApi` (`AddOpenApi()` / `MapOpenApi()`). Pick the approach matching the resolved TFM; never wire both.
+- Test stack majors: xunit v3 ships as the `xunit.v3` package with different runner wiring than `xunit` 2.x; AutoMapper 13+ self-registers (no `.Extensions.Microsoft.DependencyInjection` package). Match templates to what you resolved, not to package names from memory.
+
+If you are not certain a symbol exists in the resolved version, verify it (context7 docs lookup, or read the restored package surface under `~/.nuget/packages/`) **before** writing code that depends on it.
 
 ### Step 2 — Gather inputs (ask once, in one batch)
 
@@ -66,11 +77,16 @@ Use the **templates in `references/templates/`** as the source of truth for file
 - Create directories before files. On Windows shell use PowerShell `New-Item -ItemType Directory -Force`.
 - After scaffolding, run `dotnet sln add` for every project and `dotnet build` to verify the solution compiles. Report build output to the user.
 - Do **not** run `dotnet new` to create the projects — write the `.csproj` and `.cs` files directly from templates so the layout matches exactly.
+- If a `dotnet new` template IS run anyway (user's insistence): **the SDK wins on formats it owns** (`.sln` contents, `obj/`/`bin/` artifacts), **this skill wins on everything else** — overwrite template boilerplate with the skill's templates, keep this skill's project split and folder names. Reconcile deliberately and list every deviation in your report; never silently abandon the skill's patterns, never fight the SDK on formats it owns.
 
 ### Step 4 — Verify and report
 
-- Run `dotnet build` from the solution root. If it fails, fix and rebuild — never leave a broken scaffold.
+- Run `dotnet build` from the solution root. If it fails, fix the **first** error (later errors are usually cascade) and rebuild — never leave a broken scaffold.
 - Run `dotnet test` if any test project exists.
+- Do **not** run `dotnet ef migrations add` or `dotnet ef database update` yourself unless the user confirmed a reachable database — report the migration command as a next step instead. The delivery bar is the build gate, not the migration.
+- Known failure signature: `NETSDK1045` ("The current .NET SDK does not support targeting …") means the TFM you picked outruns the installed SDK — re-run `dotnet --list-sdks` and re-pin to the highest installed LTS; do not install a new SDK unprompted.
+- **A scaffold that hasn't compiled is not delivered.** Paste the actual proof lines in your report (`Build succeeded.` / `0 Error(s)`, and the `Passed! - Failed: 0` test summary). Never report success from memory of the steps you intended, and never report partial success as success — if something is red, say exactly what is red.
+- **CLI failure protocol** (applies to `dotnet new`, `dotnet sln add`, `dotnet build`, `dotnet test`): read the full error output, change exactly one thing, retry once. If the same step fails twice, stop scaffolding and surface the verbatim error to the user — do not keep generating files on top of a broken base, and do not re-run the identical command hoping for a different result.
 - Reply with a short summary: solution path, projects created, TFM chosen, package versions, next steps (e.g. "run `dotnet ef migrations add Initial -p src/{{Solution}}.Infrastructure -s src/{{Solution}}.Api`").
 
 ## Solution layout (canonical)
@@ -143,6 +159,9 @@ Every one of these is forbidden in generated code. See [`references/anti-pattern
    3. `src/{{Solution}}.Application/` (csproj + assembly marker + `Common/` with `IUserContext`, `Result<T>` if requested, `IUnitOfWork` port, `IRepository<T>` port).
    4. `src/{{Solution}}.Infrastructure/` (csproj + `Persistence/AppDbContext.cs` + `Persistence/EntityConfigurations/` folder + `Persistence/UnitOfWork.cs` + `Auth/UserContext.cs` + `DependencyInjection.cs` with `AddInfrastructure`).
    5. `src/{{Solution}}.Api/` (csproj + `Program.cs` + `Extensions/` folder + `Middlewares/ExceptionHandlerMiddleware.cs` + `Controllers/BaseController.cs` + `appsettings.json`/`appsettings.Development.json`).
+
+      **Checkpoint:** `dotnet sln add` items 1–5 and `dotnet build` now, before generating workers and tests — a failure here localizes to the core projects; a failure after the full tree does not. Apply the Step-4 failure protocol at this checkpoint too.
+
    6. `src/{{Solution}}.Workers.<Name>/` per worker requested.
    7. `tests/{{Solution}}.UnitTests/` (csproj + xUnit + NSubstitute + AutoFixture).
    8. `tests/{{Solution}}.IntegrationTests/` (csproj + `Microsoft.AspNetCore.Mvc.Testing` + `Testcontainers.MsSql`) — only if user asked for it.
@@ -173,7 +192,7 @@ For entity `{{Feature}}` (e.g. `Customer`):
 
 Template for the full slice is in [`references/templates/feature-slice.md`](references/templates/feature-slice.md).
 
-After generating: `dotnet build` then `dotnet test`. Both must pass.
+After generating: `dotnet build` then `dotnet test`. Both must pass — apply the Step-4 proof-and-failure protocol (paste the green lines; the same step failing twice = stop and surface the verbatim error).
 
 ### Mode 3 — `add-worker`
 
@@ -223,11 +242,29 @@ Look these up via context7 — do not hand-paste versions:
 - `Testcontainers.MsSql` (integration tests only)
 - `Microsoft.AspNetCore.Mvc.Testing` (integration tests only)
 
+## Final self-audit (mechanical — grep, don't recall)
+
+The **Eliminate** list is easy to hold at file 1 and forgotten by file 30. After generating and before the final build, grep the generated tree — every command must return nothing:
+
+```bash
+grep -rn "Thread.Sleep\|while (true)" src/                        # polling-loop workers
+grep -rnE "catch\s*(\(\s*Exception[^)]*\))?\s*\{\s*\}" src/       # swallowed exceptions
+grep -rn "ExpandoObject\|DataRow\|SqlDataAdapter" src/            # sproc-era / reflection data access
+grep -rn "GetService<" src/*/Program.cs                           # hosted services booted by hand
+grep -rn "Newtonsoft" src/                                        # unless a dependency demanded it
+grep -rln "public async Task" src/ | xargs grep -Ln "CancellationToken"   # async surface with no ct anywhere
+grep -rn "System.Data.Entity\|\"EntityFramework\"" src/           # EF6 leaking into an EF Core solution
+grep -rn "CreateDefaultBuilder" src/                               # mixed host-builder idioms
+grep -rn "/// <summary>" src/                                      # XML doc blocks on internal members
+```
+
+A hit means fix it and re-run the grep — never rationalize it away or report it as acceptable.
+
 ## Verification checklist before reporting "done"
 
 - [ ] `dotnet build` exits 0.
 - [ ] `dotnet test` exits 0 (if tests were generated).
-- [ ] No `.csproj` references violate the ONION rule (verify with `grep`/`Select-String` for cross-layer `ProjectReference`).
+- [ ] No `.csproj` references violate the ONION rule. Concrete check: `grep "ProjectReference" src/*/*.csproj` — Domain shows zero hits, Application references only Domain, Api/Workers never reference each other.
 - [ ] No file contains any pattern from the **Eliminate** list.
 - [ ] `Program.cs` is under ~50 lines (everything else is in extension methods).
 - [ ] Domain project's `.csproj` has zero `<ProjectReference>` entries.

package/skills/grill-with-docs/SKILL.md

@@ -29,10 +29,12 @@ If the user wants to build *after* grilling, hand off to `plan-and-build` and le
 ## Core principles
 
 - **One question at a time.** Always use `AskUserQuestion` with 2–4 concrete options and a recommended pick first (matches the convention used by [`plan-and-build`](../plan-and-build/SKILL.md)). Never stack three questions in one message — the user can only think clearly about one branch of the design tree at a time.
-- **Explore before asking.** If the answer is in the code, read it. Don't ask the user what `OrderService.Cancel` does when you can open the file. Ask only the questions the code can't answer.
+- **Every question must fork the design.** A question earns its slot only if different answers lead to different designs or documents. If every answer leads to the same next step, don't ask it — you're performing rigor, not applying it.
+- **Explore before asking.** If the answer is in the code, read it. Don't ask the user what `OrderService.Cancel` does when you can open the file. Ask only the questions the code can't answer. A claim about code you haven't opened this session is a **hypothesis** — label it one ("I suspect `Cancel` soft-deletes; confirming…") and read the file before building a question or an objection on it.
 - **Terminology rigor.** Surface conflicts between the user's words and the glossary on the spot. Challenge vague or overloaded terms with the canonical alternative. If the user says "account", check whether the glossary distinguishes `Customer` from `User` — and force a choice.
 - **Probe with concrete scenarios.** Invent edge cases that make abstract language fail. "What happens when two users press *Cancel* on the same order within 50ms?"
-- **Contradiction surfacing.** When stated intent contradicts what the code already does, name the discrepancy explicitly and ask which wins. Don't paper over it.
+- **Contradiction surfacing.** When stated intent contradicts what the code already does, name the discrepancy explicitly and ask which wins. Don't paper over it. An objection must cite the specific thing it conflicts with — the `CONTEXT.md` term, the ADR number, or the `file:line` you read this session. If you can't name the conflict, you don't have an objection. Zero real conflicts is a valid, reportable outcome — don't invent friction to look rigorous.
+- **Fold on preference, not on facts.** If the user's answer contradicts a documented decision or code you've cited, present the conflict once more with the citation. If they still overrule you, defer and record their call. Capitulating the moment the user pushes back — while the cited evidence still stands — is as bad as stonewalling.
 - **In-the-moment doc updates.** The moment a fuzzy term resolves, write the glossary entry into `CONTEXT.md`. Don't batch — batched updates get dropped.
 - **No code.** This skill writes only to `CONTEXT.md`, `CONTEXT-MAP.md`, and `docs/adr/*.md`. Never edit source files, never run migrations, never run tests. If the conversation reveals a code-level bug, note it and stop — that's a separate task.
 
@@ -76,6 +78,11 @@ Use `AskUserQuestion`. Lead with the recommendation, append "(Recommended)" to i
 
 If the user goes off-piste or picks "Other", absorb their answer, restate it in canonical terms, and continue.
 
+A forking question vs. a checklist question:
+
+- ❌ "Should we handle errors if the payment API fails?" — every answer is "yes"; the design doesn't move. Don't ask it.
+- ✅ "When the payment API fails mid-checkout, does the order persist as `PaymentPending` (new status + retry worker) or roll back entirely (no schema change)?" — answer A adds a status and a background job, answer B adds nothing. The answers diverge, so the question earns its slot.
+
 ## Phase 3 — Update docs in-flight
 
 As decisions crystallise, write them immediately. Two artefacts only.
@@ -112,6 +119,11 @@ Create an ADR only when **all** of:
 
 If any one of those is missing, don't write an ADR. A glossary entry or a code comment is enough.
 
+Calibration:
+
+- ❌ "Add an index on `Orders(CustomerId)`" — reversed in one migration, obvious from the query plan, no seriously-considered alternative. No ADR; it's just code.
+- ✅ "Webhook delivery becomes at-least-once via queue" — consumers must be idempotent forever (hard to reverse), sync was the obvious default (non-obvious), and outbox / sync-with-retries were genuinely weighed (real trade-offs). Write the ADR.
+
 #### ADR template
 
 Drop into `docs/adr/NNNN-short-title-kebab.md`, numbered sequentially after the highest existing ADR:
@@ -147,7 +159,7 @@ Keep ADRs immutable once accepted. If the decision changes, write a new ADR that
 
 Stop grilling when **any** of these are true. Don't pad the conversation.
 
-- Further questions stop changing the design — the next question's answer wouldn't move a file or change a name.
+- Further questions stop changing the design — the next question's answer wouldn't move a file or change a name. Operational check: **if the last two answers changed nothing** — no glossary entry, no renamed term, no design fork — the interview is done; summarise and move to crystallisation. Don't stop after two questions because the surface looks calm, and don't grill past the point where answers stop moving files.
 - All terms in the user's spec have a matching `CONTEXT.md` entry (existing or just-added) and no contradictions remain.
 - The user explicitly signals "good enough" — accept it, but quickly note any genuinely open questions you can see.
 - The conversation has revealed that the right next step is **not** to grill further but to prototype, diagnose, or pick a different scope. Say so and stop.
@@ -163,6 +175,10 @@ When you stop, produce a short closing summary:
 
 - Asking three questions in one message. One at a time, with options.
 - Asking the user something the codebase already answers. Read first, ask second.
+- Asking questions whose every answer leads to the same next step. If the answer can't fork the design, cut the question.
+- Raising an objection that cites nothing. Name the `CONTEXT.md` term, ADR, or `file:line` it conflicts with — or drop it. "No conflicts found" is a valid result.
+- Folding on first pushback while the cited evidence still stands. Restate the conflict once with the citation, then defer.
+- Asserting what code does without having read it this session. Unread-code claims are hypotheses — say so.
 - Letting a vague term ("account", "user", "delete", "cancel", "process") slide because the user used it confidently.
 - Adding code, tests, or migrations during this skill. Out of scope.
 - Writing an ADR for a decision that's easily reversed, obvious from the code, or had no real alternative.

package/skills/handoff/SKILL.md

@@ -107,6 +107,11 @@ Read `.claude/handoffs/<this-filename>.md` first.
 
 The **Next Session Prompt** is the most important section — it's what the user pastes into the new chat to bootstrap continuity. Write it so a fresh Claude with no prior context can act on it immediately.
 
+A prompt that survives a fresh session vs. one that doesn't:
+
+- ❌ "**Goal:** Continue working on auth. **Then:** finish the remaining fixes." — which file? what's broken? what command shows it? Every answer lives in the dead session.
+- ✅ "**Goal:** Make `linkAccount` merge OAuth identities instead of erroring. **Start by reviewing:** `src/auth/link.ts` (the `linkAccount` stub at line 42), `src/auth/__tests__/link.test.ts`. **Then:** implement the merge branch for the `existing-verified-email` case; run `pnpm vitest run src/auth -t linkAccount` — currently failing with `Error: account already exists`." — names the file, the failing test, the exact command, and the next action.
+
 ## Workflow
 
 1. **Scan the current conversation** for: the stated objective, files you've read or edited, decisions made (and the reasoning), commands run, errors hit, and open threads.
@@ -115,13 +120,16 @@ The **Next Session Prompt** is the most important section — it's what the user
 4. **Pick the filename** — today's date + short slug.
 5. **Create `.claude/handoffs/` if missing**, then write the file with the Write tool.
 6. **Write the memory pointer** to the auto-memory directory and index it in `MEMORY.md`.
-7. **Report back**: tell the user the file path, the slug, and quote the Next Session Prompt so they can copy it without opening the file.
+7. **Run the zero-context self-test.** Re-read the Next Session Prompt as if you knew nothing about this conversation: does it name the exact files, the exact command to run, the current failing state, and the immediate next action? If answering any of those requires this conversation, the hand-off is not done — fix it before reporting.
+8. **Report back**: tell the user the file path, the slug, and quote the Next Session Prompt so they can copy it without opening the file.
 
 ## Verifying before you write
 
 - If you reference a file path, confirm it exists (or that you created it this session).
 - If you reference a command, make sure it's the one that actually works in this repo (check `package.json`, `Makefile`, etc.).
 - If a decision in the conversation was reversed later, record the final decision — not the abandoned one.
+- **Exact artifacts, never paraphrases.** Commands verbatim and runnable (`pnpm vitest run src/auth -t linkAccount`, not "run the auth tests"). Failing test names copied from actual runner output. Branch name from `git branch --show-current`. Uncommitted-state description from actual `git status` output — never from memory of what you think you edited.
+- If tests were failing when work stopped, re-run them now and quote the exact failure. "Some tests failing" forces the next session to rediscover which — that's the context loss this skill exists to prevent.
 
 ## Examples
 
@@ -147,6 +155,8 @@ The new session reads the referenced hand-off file first, confirms files still e
 - Dumping the entire conversation transcript — hand-off is a synthesis, not a log.
 - Forgetting the memory pointer — without it, the next session won't know the hand-off exists unless the user remembers to paste the prompt.
 - Skipping the **Next Session Prompt** section — that's the single highest-value piece of the doc.
+- Quoting commands, test names, or branch names from memory instead of from actual output. `git status`, `git branch --show-current`, and the test runner are the sources of truth.
+- Shipping a Next Session Prompt that fails the zero-context self-test — if understanding any part of it requires this conversation, it's a summary, not a hand-off.
 
 ## Notes
 

package/skills/improve-codebase-architecture/SKILL.md

@@ -59,15 +59,23 @@ Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't
 
 Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
 
+**Evidence gates — both must hold before anything becomes a candidate:**
+
+- **Friction must be observed, not theoretical.** Cite the pain: the awkward call sites (`file:line`), the shotgun-surgery pattern ("these 4 files change together — check `git log --oneline -- <dir>`"), the test that needs 40 lines of setup to exercise one branch. "This could be cleaner" with no cited pain is not a candidate.
+- **Read before ruling.** A claim about a module you haven't opened this session is a hypothesis. Before ruling on the deletion test, read the module **and at least 2 of its call sites**. The operational form of the test: if every caller could call the layer below directly with no loss of clarity, the module fails — it's a pass-through. If deleting it would smear real logic (validation, ordering, error translation) across its callers, it passes.
+
 ### 2. Present candidates
 
 Present a numbered list of deepening opportunities. For each candidate:
 
 - **Files** — which files/modules are involved
 - **Problem** — why the current architecture is causing friction
+- **Evidence** — the observed friction, cited: the call sites you read (`file:line`), the co-changing files, the awkward tests. No citation, no candidate.
 - **Solution** — plain English description of what would change
 - **Benefits** — explained in terms of locality and leverage, and also in how tests would improve
 
+**Zero candidates is a valid outcome.** A healthy codebase produces a short or empty list. Report "no deepening opportunities found — here's what I checked" rather than padding the list with theoretical refactors to appear thorough.
+
 **Use `CONTEXT.md` vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
 
 **ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly (e.g. _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
@@ -94,7 +102,7 @@ Side effects happen inline as decisions crystallize:
 
 **Claude:**
 1. **Explore.** Reads `CONTEXT.md` (sees `Order`, `OrderLine`, `Cart`) and `docs/adr/0004-validation-pipeline.md`. Spawns Explore on `src/orders/validation/` and finds 11 single-function modules (`validateSku.ts`, `validateQty.ts`, …) each called from one place in `OrderIntake`.
-2. **Candidates.** Presents one numbered candidate: "Collapse the `validate*` cluster into a deep `OrderIntakeValidator` module — current shallow validators have interface nearly as complex as implementation; the real bugs hide in how `OrderIntake` *composes* them, where no test exercises the seam." Files / Problem / Solution / Benefits. Notes: does not contradict ADR-0004 (which is about *when* to validate, not *how* to compose validators).
+2. **Candidates.** Presents one numbered candidate: "Collapse the `validate*` cluster into a deep `OrderIntakeValidator` module — current shallow validators have interface nearly as complex as implementation; the real bugs hide in how `OrderIntake` *composes* them, where no test exercises the seam." Files / Problem / Evidence (the `OrderIntake` call site read, plus the two `validate*` modules opened for the deletion test) / Solution / Benefits. Notes: does not contradict ADR-0004 (which is about *when* to validate, not *how* to compose validators).
 3. **Grilling.** User picks the candidate. Walks the design tree: dependency category (in-process, [DEEPENING.md](DEEPENING.md) §1), seam placement (one external seam at `OrderIntakeValidator`, internal validators stay private), test surface (assert at `validate(order) → Result<Order, ValidationError[]>`, delete the 11 per-function tests). Adds `OrderIntakeValidator` to `CONTEXT.md`.
 
 ### Example 2: A candidate that contradicts an ADR — but worth reopening
@@ -106,6 +114,8 @@ Side effects happen inline as decisions crystallize:
 ## Anti-patterns
 
 - ❌ Proposing a refactor without applying the **deletion test** — leads to suggestions that just move complexity instead of concentrating it.
+- ❌ Ruling on the deletion test from a module's name or the file listing. Read the module and ≥2 call sites first; until then it's a hypothesis, not a candidate.
+- ❌ Manufacturing candidates from theoretical concerns: ❌ _"`OrderMapper` could be more flexible"_ (no cited pain) vs. ✅ _"`OrderMapper`'s 3 call sites each re-wrap its output (`intake.ts:41`, `sync.ts:88`, `api.ts:120`) — the seam is in the wrong place."_ The first pads the list; the second names the friction.
 - ❌ Naming things "FooHandler" / "BarService" / "BazManager" when `CONTEXT.md` already names the concept. Use the domain term.
 - ❌ Introducing a port + adapter for a dependency with only one implementation. **One adapter = hypothetical seam.**
 - ❌ Re-litigating an ADR without explicit cause. ADRs are decisions the skill should _not_ reopen unless the constraint that drove them is gone.

package/skills/nextjs-app-router/SKILL.md

@@ -60,6 +60,17 @@ Versions are resolved at scaffold time, never hard-pasted into the skill. Before
 3. Quote the resolved versions back to the user before generating, so they can object.
 4. Prefer the latest **stable** Next.js (App Router GA from 13.4; resolve current).
 5. Default to **pnpm** if `pnpm` is present, otherwise **npm**. Match `packageManager` in `package.json`.
+6. Concrete resolution command when context7 is unavailable: `npm view <pkg> version` (e.g. `npm view next version`; `npm view next-auth dist-tags` — plain `npm view next-auth version` returns the latest *stable*, which may still be v4; never scaffold v4). Never write a version you did not just resolve this session — no versions from memory, no `latest`/`^latest`, no invented numbers.
+7. **API-drift guard.** The version you resolved in this step decides the API shape — training-data memory is the least trustworthy source in this workflow. Highest-risk hallucination zones:
+   - NextAuth **v4 patterns are POISON here**: `authOptions` export, `getServerSession`, `NEXTAUTH_*` env vars, an options object in the `[...nextauth]` route. v5 is `const { handlers, auth, signIn, signOut } = NextAuth(config)` in `src/auth.ts`, with `AUTH_*` env vars.
+   - App Router signatures that changed across majors — e.g. in Next 15 `params`/`searchParams` are **Promises** in dynamic route segments and Route Handler contexts; check the resolved major before writing `params.id`. In `'use client'` pages read route params with `useParams()` from `next/navigation`, not the `params` prop.
+   - RTK Query / Redux Toolkit option names (`fetchBaseQuery` options, `providesTags`/`invalidatesTags` shapes) and the Prisma client API for the resolved major.
+   - Tailwind majors: v4 dropped the `tailwind.config.ts`-first setup for CSS-first config (`@import "tailwindcss"` + `@tailwindcss/postcss`); v3 uses `tailwind.config.ts` + `postcss.config.js`. Emit exactly one style — the one matching the resolved major — never a mix.
+   - Zod majors: v4 moved/renamed APIs (top-level `z.email()`, reworked error customization). A v3-only signature against a resolved v4 is a hallucination — check the installed types under `node_modules/zod`.
+   - Prisma majors: the `generator` block shape and default client output location changed across majors. After `prisma generate`, confirm the actual import path from what was generated — don't assume `@prisma/client` from memory.
+   - The shadcn CLI is `npx shadcn@latest` (`init` / `add`); the old `shadcn-ui` package name is dead.
+
+   If you are not certain a symbol exists in the resolved version, verify it (read the installed types under `node_modules/<pkg>/`, or check docs) **before** writing code that depends on it.
 
 ### Step 2 — Gather inputs (ask once, in one batch)
 
@@ -85,6 +96,7 @@ Use the **templates in [`references/templates/`](references/templates/)** as the
 - Create directories before files. On Windows shell use PowerShell `New-Item -ItemType Directory -Force`.
 - Do **not** run `create-next-app` to bootstrap — write files directly from templates so the layout matches [`references/folder-layout.md`](references/folder-layout.md). Use `npm`/`pnpm install` after `package.json` is written.
 - Initialize shadcn/ui by writing `components.json` from [`references/templates/components-json.md`](references/templates/components-json.md) and `src/components/ui/` components incrementally as needed (button, input, form, label, dialog, toast, etc.) — don't blanket-install every Radix primitive.
+- If a generator IS run (`shadcn` CLI, `prisma init`, or `create-next-app` at the user's insistence) and its output differs from this skill's layout: **the framework wins on file locations it mandates** (`middleware.ts` placement, `app/` conventions, `prisma/schema.prisma`), **this skill wins on everything the framework doesn't mandate** (redux layout, route groups, `_components`/`_hooks`). Reconcile deliberately and list every deviation in your report — never force the skill layout over a framework requirement, never silently abandon the skill's patterns.
 
 ### Step 4 — Database setup
 
@@ -97,6 +109,7 @@ After `package.json` and `prisma/schema.prisma` are written:
    - **Never run `prisma db push` against a production-shaped database.** Use migrations.
    - **Never run `prisma migrate reset` without explicit user confirmation** — it drops the DB.
 5. Generate `AUTH_SECRET` for the user: `pnpm exec auth secret` (Auth.js CLI) or `openssl rand -base64 32`. Put it in `.env.local` (NOT `.env.example`).
+6. Order is load-bearing: `prisma generate` MUST run before `pnpm typecheck` / `pnpm build` — the `@prisma/client` types don't exist until generated. If typecheck explodes with missing Prisma types, you skipped or mis-ordered this step; run generate, don't start rewriting imports.
 
 ### Step 5 — Verify and report
 
@@ -104,6 +117,8 @@ After `package.json` and `prisma/schema.prisma` are written:
 - `pnpm lint`. Must exit 0.
 - `pnpm test` (Vitest) if any tests were generated. Must exit 0.
 - `pnpm build`. Must succeed.
+- **A scaffold that hasn't built is not delivered.** Paste the actual proof lines in your report (Next's `✓ Compiled successfully`, Vitest's `Tests  N passed`). Never report success from memory of the steps you intended, and never report partial success as success — if something is red, say exactly what is red.
+- **CLI failure protocol** (applies to `pnpm install`, `prisma migrate`, `pnpm build`, etc.): read the full error output, change exactly one thing, retry once. If the same step fails twice, stop scaffolding and surface the verbatim error to the user — do not keep generating files on a broken base, and do not re-run the identical command hoping for a different result.
 - Reply with a short summary: project path, versions chosen, route groups, env vars to set (especially `AUTH_SECRET` and `DATABASE_URL`), next steps (`pnpm dev`, log in with the seeded test user if Credentials was chosen).
 
 ## Project layout (canonical)
@@ -302,7 +317,7 @@ For feature `{{Feature}}` in route group `{{Group}}` (e.g. `(app)`):
    - `_components/{{Feature}}Form.tsx` — `'use client'`, uses `useForm` + `zodResolver`, wraps `<UnsavedChangesWarning>`, dispatches create/update mutation on submit.
 7. **Tests**: `tests/unit/{{feature}}.schema.test.ts` (Zod schema valid + invalid). Optional handler test that mocks `db` and `auth`.
 
-After generating: `pnpm typecheck && pnpm test && pnpm build`.
+After generating: `pnpm typecheck && pnpm test && pnpm build`. Apply the Step-5 proof-and-failure protocol — paste the green lines; the same step failing twice = stop and surface the verbatim error.
 
 ### Mode 3 — `add-api-slice`
 
@@ -315,10 +330,27 @@ For domain `{{domain}}` (e.g. `customers`):
 5. Add the Prisma model(s) and migrate if needed.
 6. **Do not** create a new `createApi(...)`. One base `api`, many injected slices.
 
-After generating: `pnpm typecheck && pnpm build` must pass.
+After generating: `pnpm typecheck && pnpm build` must pass — Step-5 proof-and-failure protocol applies.
 
 ## Verification checklist before reporting "done"
 
+Run this as a **mechanical pass over the generated tree** — grep, don't recall. The forbidden list is easy to hold at file 1 and forgotten by file 30; do not answer any item from memory of what you intended to write. Start with this grep block — every command must return nothing:
+
+```bash
+grep -rn "'use server'" src/                                     # Server Actions
+grep -rn "export default async function" src/app --include='page.tsx'   # async pages
+grep -rn "from '@/lib/db'" src/app --include='*.tsx'             # DB access outside route.ts
+grep -rn "fetch(" src/app src/components --include='*.tsx'       # inline fetch in components
+grep -rn "serializableCheck: false\|@ts-ignore\|as any" src/redux src/app/api
+grep -rn "moment" src/ package.json                              # date-fns only
+grep -rn "NEXTAUTH_\|getServerSession\|authOptions\|next-auth/next" src/ .env.example   # NextAuth v4 leaking in
+grep -rn "styled-components\|@emotion" src/ package.json          # CSS-in-JS in a Tailwind project
+grep -rn "localStorage\|sessionStorage" src/                      # any token/session hit is a bug
+grep -rn "dangerouslySetInnerHTML" src/                           # zero on a fresh scaffold
+```
+
+A hit means fix it and re-run the grep — never rationalize it away. Then the full checklist:
+
 - [ ] `pnpm install` succeeds.
 - [ ] `pnpm exec prisma generate` succeeds.
 - [ ] `pnpm exec prisma migrate dev --name init` succeeds (or the user confirmed they ran it manually).
@@ -330,7 +362,8 @@ After generating: `pnpm typecheck && pnpm build` must pass.
 - [ ] Every `route.ts` file in `src/app/api/**` (except `[...nextauth]`) calls `await auth()` or `await requireSession()`.
 - [ ] No `'use server'` directive anywhere. Grep: `grep -rn "'use server'" src/` returns nothing.
 - [ ] No `async function .*Page` in any `page.tsx`. Pages are sync `'use client'`.
-- [ ] No `serializableCheck: false`, `@ts-ignore`, `as any` in `src/redux/**` or `src/app/api/**`.
+- [ ] No `serializableCheck: false`, `@ts-ignore`, `as any` in `src/redux/**` or `src/app/api/**` (covered by the grep block above).
+- [ ] Exactly one `createApi(` in the codebase (the base `api`). Grep: `grep -rn "createApi(" src/` shows one hit.
 - [ ] `middleware.ts` exists at project root; its `config.matcher` excludes `/api/auth` (NextAuth handles its own routes).
 - [ ] `src/auth.ts` and `src/auth.config.ts` both exist. `auth.config.ts` has no `@/lib/db` import (Edge-safe).
 - [ ] `.env` is **not** committed; `.env.example` is. `AUTH_SECRET` is **not** in `.env.example` (it's documented as required, with instructions to generate it).

package/skills/plan-and-build/SKILL.md

@@ -32,6 +32,9 @@ If the feature is large, fuzzy, or still in discovery — defer to [`grill-with-
 Rules:
 
 - **One question at a time.** Wait for the answer before the next one. Use `AskUserQuestion` with 2–4 concrete options and a recommended pick first.
+- **A question earns its slot only if different answers lead to different designs.** Before asking, name (to yourself) what changes per answer. If every answer leads to the same next step, don't ask it — generic checklist questions burn the user's patience without buying design information.
+  - ❌ "Should this endpoint be secure and handle errors gracefully?" — every answer is "yes"; nothing about the design forks.
+  - ✅ "When an order loses priority, do we keep the history of who set it and when?" — "yes" needs an audit table, "no" is two columns. The answer picks the schema.
 - **Explore the codebase instead of asking** when the answer is already there. If a similar feature, entity, controller, or migration exists, read it before asking the user how a related thing should work.
 - **Sharpen fuzzy language.** When the user says "account", ask: "Customer or User? Those are different things here." When they say "cancel", ask whether that means soft-delete, hard-delete, or a status transition.
 - **Probe with concrete scenarios.** Invent edge cases that force the user to be precise. "What happens if the user submits twice while the first request is still in flight?"
@@ -114,7 +117,8 @@ Whether you drafted one plan or chose between two, the presented plan must inclu
    - Whether a backfill is required and how it's gated.
    - **Always end with:** "Migration file will be generated. No SQL, no `dotnet ef database update`, no `ExecuteSql*` calls will be run — the user runs the migration themselves."
 6. **Pattern reuse table.** Two columns: "New code I'm about to write" and "Existing example it follows" with a path. If a row has no existing example, justify the new pattern.
-7. **Open questions** still unresolved, if any. If there are any, loop back to Phase 1 — do not exit plan mode with open questions.
+7. **Validation signal per step.** Every build step names the observable signal that proves it done at plan time — a named test going green, `dotnet build` exiting 0, a `curl` returning the expected body. A step whose completion can't be observed isn't a step, it's a hope — split it or attach a signal before presenting.
+8. **Open questions** still unresolved, if any. If there are any, loop back to Phase 1 — do not exit plan mode with open questions.
 
 If Design It Twice ran, end the plan with: **"Considered alternative: `<approach B name>`. Rejected because `<one-line reason>`."** This lets the user redirect to B with a single sentence if they disagree.
 
@@ -126,6 +130,8 @@ Enter Plan Mode (`EnterPlanMode`) to present. Then exit with `ExitPlanMode` and
 
 Build in the order that gives you the fastest feedback loop.
 
+**The plan is a hypothesis about the codebase.** When execution contradicts it — the pattern Phase 2 found doesn't cover this case, the library API has a different shape, the file the plan modifies doesn't exist — stop. Do not improvise silently and keep typing. Re-plan the remaining steps against what you just learned, tell the user what deviated and why, and re-present via plan mode if the change is material (different files, different schema, a new dependency). A small deviation (a helper's actual name, a slightly different signature) just gets a one-line note in the Phase 6 report.
+
 **If the feature adds or changes an API endpoint, follow TDD:**
 
 1. **Locate the test class.** For each API change, search for an existing test class that already covers that controller / service / use-case. Common patterns:
@@ -153,6 +159,7 @@ Build in the order that gives you the fastest feedback loop.
 - **Minimal comments.** Default to no comments. Only add one when the *why* is non-obvious (a workaround, a non-trivial invariant, a domain rule that isn't visible from the names). Never write block headers, never restate what the next line does, never leave `// TODO` without an issue link.
 - **Match formatting.** Use the project's brace style, naming, file headers, `using` placement. Don't reformat unrelated code.
 - **No dead code.** Don't commit commented-out lines or "for future use" stubs.
+- **Build to the plan, nothing more.** Done means the approved plan's acceptance criteria. No unrequested config options, no defensive layers the plan didn't ask for, no speculative extension points. Improvements you notice mid-build are findings for the Phase 6 report, not work to do.
 
 ### Phase 5 — Migrations (generate only, never execute)
 
@@ -207,7 +214,10 @@ When appending:
 ## Anti-patterns
 
 - ❌ Skipping Phase 1 and going straight to "let me read the code and start building" — the whole point of this skill is the grill.
+- ❌ Asking grill questions whose answers all lead to the same design. Every question must fork the design.
 - ❌ Exiting plan mode while open questions remain. Loop back instead.
+- ❌ Improvising silently when the codebase contradicts the plan. Stop, re-plan the remainder, tell the user what deviated.
+- ❌ Gold-plating the build: config options, abstraction layers, or "robustness" the plan never called for.
 - ❌ Writing production code before the test it makes pass (when the feature touches an API).
 - ❌ Creating `FooServiceTests2.cs` because `FooServiceTests.cs` already exists. Always append.
 - ❌ Inventing a new pattern for something the codebase already has a pattern for. If you can't find the precedent, ask before forking.

package/skills/pr-review/SKILL.md

@@ -54,6 +54,26 @@ Categorize each comment so the author knows what's required vs optional:
 
 Lead with the *why*, not just the *what*. "This will deadlock if two callers hit it simultaneously" is more useful than "use a lock here".
 
+Same finding, badly and well:
+
+- ❌ `blocking: add error handling to fetchUser (api/user.ts:42)` — no failure scenario, no consequence; unverifiable reflex.
+- ✅ `blocking: fetchUser (api/user.ts:42) rejects on 404 but ProfilePage (pages/profile.tsx:18) never catches — a deleted user's profile renders blank with an unhandled rejection. Fix: catch and render not-found.`
+
+## Evidence rules
+
+A claim about code you haven't opened this session is a hypothesis — verify it or label it as one.
+
+- **Read beyond the hunk.** Before flagging anything, `Read` the full enclosing function (the whole file when small). Most false "missing null check" / "unhandled error" findings dissolve when you see the guard 10 lines above the hunk or the caller that validates. A finding based only on diff-hunk context is not reportable.
+- **`blocking` carries a burden of proof:** one concrete failure-scenario sentence (*this input/state → this wrong outcome*). Can't write it? Demote to `suggestion`, or raise it as a `question`.
+- **Grep before claiming absence.** "Dead code" / "unused" / "never called" / "duplicated elsewhere" require a repo-wide `Grep` for the identifier first — cite the search in the finding.
+- **Quote verbatim.** Error messages, test output, and load-bearing identifiers go into findings exactly as they appear; paraphrase loses the token that matters.
+- **Zero findings is a valid verdict.** A task with nothing wrong gets a clean *Approve* — never pad Blockers or Suggestions to look thorough. Thoroughness is what you checked, not what you wrote.
+- **User framing is input, not conclusion.** "The backend part is fine, just look at the UI" does not exempt the backend — review every task fully.
+
+## Scope discipline
+
+A finding must belong to the task (`#NNN`) whose diff introduced it. Pre-existing code that's merely *visible* in the diff context is out of scope — unless the task made it worse (e.g. added a second caller to an already-unsafe function; that's in scope). If you notice a pre-existing issue worth mentioning, note it in one line outside the verdict ("pre-existing, not introduced by #123") — never block a task for code its commits didn't touch.
+
 ## What to look for
 
 ### Correctness
@@ -117,7 +137,7 @@ Performance + Readability usually fold into Design — only spawn a dedicated le
    - The per-task diff (commits from this `#NNN` only — not the whole branch).
    - The inferred task intent from step 4.
    - **One** lens with its checklist verbatim from [What to look for](#what-to-look-for).
-   - Instructions: "Find issues only in your lens. Categorize each as `blocking` / `suggestion` / `question` / `nit`. Cite `file:line` for every finding. Lead each with the *why*. If no findings, say 'no findings' explicitly. Report in ≤500 words."
+   - Instructions: "Find issues only in your lens. Read the full enclosing function before flagging — hunk-only findings are not reportable. Only flag code this task's commits introduced or worsened; pre-existing issues are out of scope. Categorize each as `blocking` / `suggestion` / `question` / `nit`; a `blocking` must state a one-sentence concrete failure scenario. Cite `file:line` for every finding. Lead each with the *why*. If no findings, say 'no findings' explicitly — do not pad. Report in ≤500 words."
 2. **Critique round.** Read all lenses side by side, then:
    - **Challenge every `blocking`** against context from the other lenses. Demote to `suggestion` or drop if it's defused by another lens's evidence.
    - **Surface contradictions** as `question` items the user adjudicates (e.g. Correctness flags missing null guard; Security found the caller validates).
@@ -170,6 +190,10 @@ End with a one-line roll-up: e.g. `Overall: 2 approve, 1 request changes, 1 unsc
 - ❌ Reflexively requesting tests without saying what they should cover
 - ❌ Drive-by style nits that derail the substantive discussion
 - ❌ "I would have done it differently" without a concrete reason
+- ❌ Flagging from the diff hunk alone — read the enclosing function first; the guard is often just outside the hunk
+- ❌ Blocking a task for a pre-existing issue its diff didn't introduce or worsen — note it in one line, out of verdict
+- ❌ A `blocking` with no concrete failure scenario — if you can't write "this input → this wrong outcome", it isn't blocking
+- ❌ Padding a clean task with speculative findings — zero findings is a valid Approve
 - ❌ Collapsing multiple tasks into one verdict — each `#NNN` is independent and should stand or fall on its own
 - ❌ Silently ignoring commits with no task reference — surface them in the `unscoped` bucket
 - ❌ Convening the lens council on a 20-line task. Single-pass it.

package/skills/ship-it/SKILL.md

@@ -20,7 +20,8 @@ Do **not** auto-trigger when the user is asking about diff-level code quality, D
 
 - **Recommend, don't refactor.** This is an audit. Never edit code unprompted. After the report, ask per-blocker whether the user wants a fix drafted.
 - **Evidence is mandatory.** Every PASS must cite `file:line`. "I checked, it looks fine" is not a PASS — that's a GAP labelled `couldn't verify`.
-- **N/A needs a reason.** Mark a category N/A only with a one-line justification (e.g. *"server-only service, no local storage layer"*). Don't fabricate gaps for categories that don't apply.
+- **Name the probe.** Every PASS also names the exact check that produced its evidence — the grep pattern + path, the file you read, or the command you ran. If you didn't run a probe for an item, it's GAP labelled `not checked` — never PASS. A result you didn't observe doesn't exist.
+- **N/A needs a reason grounded in the scope.** The justification must derive from an observed fact about *this* scope, with the probe that established it (e.g. *"no files under `migrations/` in the diff (`git diff --stat`) → migrations N/A"*) — never a guess from the project type. Don't fabricate gaps for categories that don't apply.
 - **Stay in your lane.** Don't re-do `code-review`'s work. If the user asks about DRY / dead code / test coverage, defer.
 
 ## Workflow
@@ -40,6 +41,8 @@ Echo the scope back in one line before starting Phase 2 (*"Auditing branch `feat
 
 For each category: state the criterion in one line, search the codebase for evidence, mark PASS / GAP / N/A. Use `Grep` and `Read` aggressively; spawn an `Explore` sub-agent for any category where the search would take more than 3 queries.
 
+Record each probe as you run it — the report cites them. A probe is a specific `Grep` pattern + path, a `Read` of a named file, or a command with its observed output. A sub-agent's result counts as a probe only if the sub-agent names its own probes and citations; "the agent said it's fine" is not evidence. Where a check depends on the user (dashboards, runbooks, rollout plans), record their answer as the probe (*"user confirmed: alert added to Grafana billing board"*) — an unanswered question stays GAP.
+
 #### 1. Logging
 
 **What good looks like:** Structured logs (JSON or key=value), correlation / request IDs propagated, levels used correctly (`error` ≠ `info`), no secrets / tokens / PII in log output, errors logged with stack + context, not just the message.
@@ -118,12 +121,17 @@ Group findings into four buckets. Order matters — blocking first.
 - **<category>:** <one-line problem> — `<file:line>`
 
 ## N/A
-- **<category>:** <one-line reason>
+- **<category>:** <one-line reason grounded in the scope> (probe: `<what established it>`)
 
 ## Passing
-- **<category>:** <one-line evidence> — `<file:line>`
+- **<category>:** <one-line evidence> — `<file:line>` (probe: `<grep pattern / file read / command>`)
 ```
 
+Same PASS, written badly and well:
+
+- ❌ `**Logging:** structured logging in place — src/billing/` — no line, no probe; unverifiable, could have been written without looking.
+- ✅ `**Logging:** new invoice paths log via structured logger with request ID — src/billing/invoice.ts:31 (probe: grep -n "logger\." src/billing/ → 6 call sites, all pass ctx.reqId)` — anyone can rerun the probe and land on the same line.
+
 **Blocking = any one of:**
 - Secrets in code / logs / committed config.
 - Missing authz on a new endpoint or screen.
@@ -145,8 +153,8 @@ After the report, ask: *"Want me to draft fixes for the blocking items, or stop
 
 **Claude:**
 1. Echoes scope: *"Auditing `feat/billing-v2` against `main` — 14 files changed."*
-2. Walks the 10 categories, citing `file:line` per finding.
-3. Reports: 2 blocking (missing authz on `POST /api/v2/invoices`, no rollback for the `currency_code NOT NULL` migration), 4 should-fix, 1 N/A (local-first storage — server-only), 3 passing.
+2. Walks the 10 categories, citing `file:line` per finding and the probe that produced it.
+3. Reports: 2 blocking (missing authz on `POST /api/v2/invoices` — `no tenant predicate in routes/invoices.ts:24-51, read top-to-bottom`; no rollback for the `currency_code NOT NULL` migration), 4 should-fix, 1 N/A (local-first storage — *"no client-side store in scope: `grep -rl 'localStorage\|indexedDB' src/billing/` → 0 hits, server-only module"*), 3 passing with probes named.
 4. Asks whether to draft fixes for the blockers.
 
 ### Example 2: Module-scoped audit
@@ -167,6 +175,8 @@ After the report, ask: *"Want me to draft fixes for the blocking items, or stop
 ## Anti-patterns
 
 - ❌ Marking a category PASS without a `file:line` citation. "Looks fine" is a GAP labelled `couldn't verify`.
+- ❌ PASS on vibes — a PASS with no named probe (the grep / read / command that produced the evidence) is a GAP labelled `not checked`.
+- ❌ N/A from a guess about the project type. Derive it from the scope and name the probe: *"no schema files in this diff (`git diff --stat`) → migrations N/A"*.
 - ❌ Inventing GAPs in N/A categories. A server-only service genuinely has no local-first storage layer — say so and move on.
 - ❌ Reviewing diff quality (DRY, dead code, missing tests) under the ship-it banner. Defer to `code-review`.
 - ❌ Editing code mid-audit. The report comes first, then the user picks what to fix.

package/skills/sql-review/SKILL.md

@@ -46,6 +46,20 @@ SQL changes are particularly sensitive because they often run against production
 
 Lead each finding with the *why*. "This swallows the original error and surfaces a misleading permission denial" beats "add `;THROW;`".
 
+## Pattern hit ≠ finding
+
+The 17 checks are pattern matches. A ripgrep hit is a **candidate** — before reporting it, `Read` the whole procedure/batch it sits in; severity depends on context the pattern can't see. Concrete demotions:
+
+- `WITH (NOLOCK)` hit, but the proc is a read-only reporting proc with no `INSERT`/`UPDATE`/`DELETE` → **WARN** at most, not BLOCKER (check #13 blocks only when the same proc writes the tables it dirty-reads).
+- `DECLARE @retry` with no `WHILE @retry` in sight → check for a `GOTO`-label retry loop consuming it before flagging; only report when nothing reads the variable.
+- New `CREATE TABLE` with no index, but it's a static lookup/config table seeded with a handful of rows in the same diff → **WARN** with a one-line reason, not BLOCKER (the deadlock incident needs growth under concurrent writes).
+
+Every reported finding must:
+1. **Quote the offending SQL verbatim** — the exact line(s) from the file, not a paraphrase. Severity turns on exact tokens.
+2. For `BLOCKER` / `WARN`: state the concrete production incident in one sentence (*this state → this outcome*, e.g. "first deadlock under load → SP silently gives up, rows never written"). If you can't write that sentence after reading the full proc, demote one level.
+
+Zero findings is a valid outcome — a clean diff gets a clean report. Never stretch INFO items into WARNs to fill sections; thoroughness is the 17 checks you ran, which the report shows.
+
 ## What to check
 
 Use ripgrep for detection. The patterns below are starting points — adapt to the actual diff text.
@@ -148,6 +162,7 @@ Use ripgrep for detection. The patterns below are starting points — adapt to t
 ## Blockers (<N>)
 
 ### B1. <short title> — `path/to/file.sql:<line>`
+**Evidence:** `<offending SQL fragment, quoted verbatim>`
 **Why:** <root cause / production consequence — one line>
 **Fix:** <concrete recommendation — one line>
 
@@ -156,6 +171,7 @@ Use ripgrep for detection. The patterns below are starting points — adapt to t
 ## Warnings (<N>)
 
 ### W1. <short title> — `path/to/file.sql:<line>`
+**Evidence:** `<offending SQL fragment, quoted verbatim>`
 **Why:** ...
 **Fix:** ...
 
@@ -220,6 +236,10 @@ End with the offer. Wait for the user's choice.
 - ❌ Suggesting autofixes for `BLOCKER` items without asking. SQL deploys to production; user confirmation gates the change.
 - ❌ Listing a `nit` when there's a `BLOCKER` next to it. Lead with severity.
 - ❌ Hand-wavy findings without `file:line`.
+- ❌ Reporting a raw ripgrep hit without reading the surrounding procedure. A pattern match is a candidate; the proc's full context sets the severity (see [Pattern hit ≠ finding](#pattern-hit--finding)).
+- ❌ Paraphrasing the offending SQL instead of quoting it verbatim. `WITH (NOLOCK)` vs `READPAST`, `@retry` vs `@retryCount` — the exact token is the finding.
+- ❌ A `BLOCKER` with no one-sentence production-incident scenario. Can't name the incident? It's a `WARN`.
+- ❌ Padding a clean diff with stretched findings. Zero findings is a valid report.
 - ❌ Inventing antipatterns not in [What to check](#what-to-check). This is a fixed catalog — extending it is a `write-a-skill` change, not a per-run improvisation.
 - ❌ Running on non-SQL files. The skill is `.sql`-scoped; mixed diffs route to `code-review` for the non-SQL parts.
 - ✅ Diff-scoped scan for modified files, full scan for new files, findings categorized + cited + offered as fixes.

package/skills/task-executor/SKILL.md

@@ -125,11 +125,21 @@ If the user pushes back, revise and re-present. Do not partial-implement against
 
 Walk the plan one step at a time. For each step:
 
-1. **Make the smallest change that completes the step.** No drive-by refactors, no "while I'm here" fixes, no batched edits across multiple steps.
+0. **Re-anchor.** Re-read the `Goal` section and this step's validation criterion from `Plan` before touching anything. Thirty seconds of re-reading is what keeps turn 20 aligned with turn 1 — drift is silent and this is the only cheap defense.
+1. **Make the smallest change that completes the step.** No drive-by refactors, no "while I'm here" fixes, no batched edits across multiple steps. Done means the step's criterion, nothing more — improvements you notice (missing validation, refactor opportunity, extra config) go into `Risks` as findings, not into the diff.
 2. **Validate immediately.** Run the test, build, type-check, lint, curl the endpoint, or load the page — whichever signal is appropriate for that step. If there's no automated signal at all, say so explicitly in `Progress`; don't pretend there is one.
-3. **Tick the checkbox** with a one-line evidence note (`tests pass`, `dotnet build green`, `200 OK with expected body`).
+3. **Tick the checkbox** with evidence that is an **observed artifact from this turn** — a pasted output line, an exit code, a status code. A claim is not evidence.
+   - ❌ `tests pass` — an assertion; nothing was observed.
+   - ✅ `dotnet test → Passed! 42 passed, 0 failed, 0 skipped` — pasted from output you just saw.
+   If you didn't run it this turn, you can't tick it.
 4. **Re-emit the full per-turn output** before moving to the next step.
 
+When a command fails:
+
+- Read the **full** error output — the load-bearing detail is usually in the last lines you'd skim past.
+- Change exactly one thing based on what the error says, then retry once.
+- Two failures on the same step = stop. Add the verbatim error to `Risks` and surface to the user. Never retry verbatim, and never continue as if the command succeeded — a result you didn't observe is not a result.
+
 When a validation fails:
 
 - Do not move on.
@@ -160,6 +170,9 @@ When every checkbox is ticked:
 - ❌ Convening the inspection council for a 3-file task. Ceremony for its own sake. Inline reads are the default — escalate only when the inspection set genuinely spans multiple layers.
 - ❌ Spawning the inspection sub-agents serially instead of in parallel — one message, N `Agent` calls. Serial defeats the context-protection rationale.
 - ❌ Letting a sub-agent slice overlap with another's. If two slices would re-read the same files, merge them first.
+- ❌ Ticking a checkbox with claimed evidence (`tests pass`) when the command wasn't run this turn. Evidence is pasted observation, not memory or assertion.
+- ❌ Retrying a failed command verbatim, or proceeding as if it succeeded. Read the error, change one thing, retry once; twice failed = `Risks` + stop.
+- ❌ Gold-plating a step: extra config options, defensive layers, speculative hooks the plan didn't call for. Findings go to `Risks`; the diff stays the size of the step.
 - ✅ Same six headers every turn, one step at a time, one validation per step, assumptions tracked explicitly until confirmed or killed.
 
 ## Examples

package/skills/tauri-2-app/SKILL.md

@@ -43,6 +43,8 @@ The user does **not** want hard-coded Cargo / npm versions baked into the skill.
 3. Pin the Rust edition to `2021` unless the user asks otherwise.
 4. Quote the resolved versions back to the user before generating, so they can object.
 5. Default to **npm** unless `pnpm` or `bun` is present and the user prefers it.
+6. Concrete resolution commands when context7 is unavailable: `npm view @tauri-apps/api version`, `cargo search <crate> --limit 1`, or WebFetch `https://crates.io/api/v1/crates/<crate>` (`max_stable_version`). Never write a version you did not just resolve this session — no versions from memory, no invented numbers.
+7. **Tauri 1.x is poison.** Training data is full of v1 patterns that look plausible and fail on v2. Never emit: `import { invoke } from '@tauri-apps/api/tauri'` (the v2 path is `@tauri-apps/api/core`), a `tauri.allowlist` or top-level `tauri` key in `tauri.conf.json` (v2 uses `app` / `bundle` / `plugins` + `capabilities/*.json`), or v1 plugin names/APIs. If you are not certain a conf key, capability permission string, or plugin API exists in Tauri 2, verify it against the installed schema (`node_modules/@tauri-apps/cli/config.schema.json`; valid permission strings appear in `src-tauri/gen/schemas/` after the first build) or the plugin's docs **before** writing code that depends on it. Capability `permissions` entries use the short plugin name (`dialog:allow-open`, `fs:allow-read-file`) — never a `tauri-plugin-` prefix. Note that `cargo check` compiles `tauri-build`, which validates `tauri.conf.json` and `capabilities/*.json` — a schema or unknown-permission error there is a JSON problem; fix the conf/capability file against the schema, don't edit Rust code to appease it.
 
 ### Step 2 — Gather inputs (ask once, in one batch)
 
@@ -71,14 +73,17 @@ Use the **templates in [`references/templates/`](references/templates/)** as the
 - Create directories before files. On Windows shell use PowerShell `New-Item -ItemType Directory -Force`.
 - Do **not** run `create-tauri-app` to bootstrap — write the files directly from templates so the layout matches the conventions in [`references/folder-layout.md`](references/folder-layout.md). Use `npm install` after `package.json` is written, then `cargo fetch` from `src-tauri/` to seed the Cargo cache.
 - For icons, run `npx @tauri-apps/cli icon <path-to-source.png>` once a source image exists, or generate a 1024×1024 placeholder with `sharp` if the user wants. Do **not** commit a placeholder square as the final icon — surface it as a TODO.
+- If a generator IS run (`create-tauri-app` at the user's insistence, `npx @tauri-apps/cli icon`, `tauri signer generate`) and its output differs from this skill's layout: **Tauri wins on file locations it mandates** (`src-tauri/` shape, `capabilities/`, `gen/`, icon paths), **this skill wins on everything Tauri doesn't mandate** (the `commands/`/`state/`/`storage/`/`platform/` module split, frontend hooks layout). Reconcile deliberately and list every deviation in your report — never force the skill layout over a framework requirement, never silently abandon the skill's patterns.
 
 ### Step 4 — Verify and report
 
 - Run `npm install` (or chosen PM).
-- Run `cd src-tauri && cargo build` — must exit 0. (Don't run `tauri dev` in CI — it opens a window.)
+- Run `cd src-tauri && cargo build` — must exit 0. (Don't run `tauri dev` in CI — it opens a window.) If a full `cargo build` is prohibitively slow in this environment, `cargo check` is the minimum acceptable bar — state which one you ran.
 - Run `cd src-tauri && cargo test` — must exit 0 if any tests were generated.
-- Run `npm run build` (frontend) — must exit 0.
+- Run `npm run build` (frontend) — must exit 0. `cargo check` + `npm run build` together are the floor; a full `tauri build` is optional (slow).
 - Optionally run `npm run tauri build -- --debug` if the user wants a debug bundle; skip in CI by default since it's slow.
+- **A scaffold that hasn't compiled is not delivered.** Paste the actual proof lines in your report (cargo's `Finished` profile line, `test result: ok`, Vite's `✓ built in ...`). Never report success from memory of the steps you intended, and never report partial success as success — if something is red, say exactly what is red.
+- **CLI failure protocol** (applies to `npm install`, `cargo build`/`check`/`test`, `npm run build`): read the full error output — for cargo, fix the **first** error; later ones are usually cascade. Change exactly one thing, retry once. If the same step fails twice, stop scaffolding and surface the verbatim error to the user — do not keep generating files on a broken base, and do not re-run the identical command hoping for a different result.
 - Reply with a short summary: project path, versions chosen, plugins wired, bundle identifier, next steps (e.g. "fill in the macOS `Info.plist` usage descriptions for any permissions you'll request", "generate updater keys with `npx tauri signer generate`", "run `npm run tauri dev`").
 
 ## Project layout (canonical)
@@ -236,6 +241,9 @@ Every one of these is forbidden in generated code. Rationale for each is in [`re
    3. `src-tauri/Cargo.toml` (with target-specific deps + release profile), `src-tauri/build.rs`, `src-tauri/tauri.conf.json`, `src-tauri/Info.plist`, `src-tauri/entitlements.plist`, `src-tauri/capabilities/default.json`.
    4. `src-tauri/icons/` — placeholder 1024×1024 PNG **only** if the user hasn't supplied one. Surface as TODO; tell them to run `npx @tauri-apps/cli icon icons/icon.png`.
    5. `src-tauri/src/main.rs`, `src-tauri/src/lib.rs`, `src-tauri/src/error/mod.rs`, `src-tauri/src/state/mod.rs`, `src-tauri/src/storage/mod.rs`, `src-tauri/src/commands/mod.rs` + `src-tauri/src/commands/system.rs`, `src-tauri/src/platform/{mod,traits,macos,windows,linux,wrappers}.rs`, `src-tauri/src/settings/{mod,defaults,storage,commands}.rs`.
+
+      **Checkpoint:** run `npm install` then a first `cd src-tauri && cargo check` here, before optional modules — errors localize to the core tree, and this check runs `tauri-build`, which validates `tauri.conf.json` + `capabilities/*.json` and generates `src-tauri/gen/schemas/` (the authority for valid permission strings). Fix any conf/capability error now, per the Step-4 failure protocol, before writing more capability entries.
+
    6. Optional: `src-tauri/src/encryption/mod.rs`, `src-tauri/src/tray.rs`, `src-tauri/src/commands/<more>.rs` based on user answers.
    7. `src-tauri/tests/common/mod.rs` + at least one integration test file (e.g. `system_test.rs`) so CI has something real to run.
 4. `npm install`.
@@ -261,7 +269,7 @@ For command `{{command}}` (snake_case) in module `commands/{{domain}}.rs`:
    - Export the hook. Do **not** call `invoke()` inline in a component.
 4. **Test**: add an integration test in `src-tauri/tests/{{domain}}_test.rs` that exercises the command's underlying function (the `#[tauri::command]` itself is hard to call without a full Tauri context — test the inner function).
 
-After generating: `cd src-tauri && cargo build && cargo test` then `npm run build` from the project root.
+After generating: `cd src-tauri && cargo build && cargo test` then `npm run build` from the project root. Apply the Step-4 proof-and-failure protocol — paste the green lines; the same step failing twice = stop and surface the verbatim error.
 
 ### Mode 3 — `add-module`
 
@@ -275,7 +283,7 @@ For module `{{module}}` (snake_case):
 6. Add a `#[cfg(test)]` `mod tests { ... }` block at the bottom of `mod.rs` covering pure logic (no Tauri context required).
 7. Add a `src-tauri/tests/{{module}}_test.rs` integration test if the module has cross-cutting behavior.
 
-After generating: `cd src-tauri && cargo build && cargo test`.
+After generating: `cd src-tauri && cargo build && cargo test` — Step-4 proof-and-failure protocol applies.
 
 ## NuGet... wait, this is Tauri. Cargo + npm packages (resolve latest stable at scaffold time)
 
@@ -320,6 +328,22 @@ Look these up at scaffold time — do not hand-paste versions:
 
 ## Verification checklist before reporting "done"
 
+Run this as a **mechanical pass over the generated tree** — grep, don't recall. The Eliminate list is easy to hold at file 1 and forgotten by file 30. Start with this grep block; every command must return nothing:
+
+```bash
+grep -rn "cfg!(target_os" src-tauri/src --include='*.rs' | grep -v "src/platform/"   # platform checks outside platform/
+grep -rn "@tauri-apps/api/tauri" src/                          # v1 import path (v2 is /core)
+grep -n "allowlist\|systemTray" src-tauri/tauri.conf.json      # v1 config schema leaking in (v2: capabilities/, app.trayIcon)
+grep -rn "tauri::api::" src-tauri/src --include='*.rs'         # v1 Rust API paths (v2 moved these to plugins)
+grep -rnE "pub (api_key|token|secret)\w*: String" src-tauri/src/   # plaintext secret fields (must be EncryptedApiKey)
+grep -rn "localStorage.setItem\|sessionStorage.setItem" src/   # tokens/secrets in web storage
+grep -n "\"devtools\": true" src-tauri/tauri.conf.json         # devtools enabled in release config
+grep -rn "std::fs::" src-tauri/src/commands/                   # raw fs in command bodies
+find src-tauri/src -name "*.backup" -o -name "*.orig" -o -name "*.temp"   # WIP artefacts
+```
+
+A hit means fix it and re-run the grep — never rationalize it away. Then the full checklist:
+
 - [ ] `npm install` succeeds.
 - [ ] `cd src-tauri && cargo build` exits 0.
 - [ ] `cd src-tauri && cargo test` exits 0 (if tests were generated).

package/skills/think-like-fable/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: think-like-fable
+description: An operating manual for rigorous reasoning — how to read the real request beneath the words, decompose into independently-checkable pieces, spend effort where the risk lives, verify by re-derivation instead of plausibility, label known vs. guessed, attack your own conclusion, and communicate answer-first. Apply it to the task at hand; it changes HOW you work, not WHAT you do. Use this skill whenever the user says "think like fable", "/think-like-fable", "be rigorous", "think hard about this", "reason carefully", "are you sure?", "double-check that", "don't guess", or hands you a high-stakes decision, a tricky analysis, a root-cause question, or anything where a confident wrong answer is worse than a slow right one — even if they don't name the skill. Do not load it for trivial mechanical edits or casual questions.
+---
+
+# Think Like Fable
+
+A senior operator's manual for a sharp junior. Not a rulebook to satisfy — a way of working to inhabit. Load it, then do the actual task under these disciplines. Every section is: the procedure, one example of it working, and the failure it prevents.
+
+## When to use this skill
+
+- The user says "think like fable", "/think-like-fable", "be rigorous", "think hard about this", "reason carefully", "are you sure?", "double-check that", or "don't guess".
+- The task is a high-stakes decision, root-cause analysis, architecture call, security judgment, or data-loss-adjacent change — anywhere a confident wrong answer costs more than a slow right one.
+- Another skill or agent prompt says to apply this manual to its work.
+
+Do **not** load it for trivial mechanical edits, casual questions, or tasks another skill already governs end-to-end — this manual composes *under* task skills, it doesn't replace them.
+
+## 1. Read what the request is actually asking
+
+**Procedure:** Before answering, write one sentence: "The user needs ___ so that ___." If you can't fill the second blank, you don't understand the request yet. Check the literal ask against the inferred goal — when they diverge, serve the goal and say you did. Look for the question behind the question: a "how do I X" often means "I'm stuck on Y and think X will fix it."
+
+**Example:** "How do I increase the connection pool size?" — literal ask: a config value. Actual need: their app is timing out. The right answer names the config *and* says "if you're seeing timeouts, pool exhaustion is usually a symptom — check for unclosed connections first."
+
+**Prevents:** Perfectly executing the wrong task. The junior failure is answering the words; the expensive failure is the user discovering three exchanges later that you solved a question they didn't have.
+
+## 2. Break the problem into independently checkable pieces
+
+**Procedure:** Decompose so each piece has its own pass/fail test that doesn't depend on the other pieces being right. If two pieces can only be verified together, the cut is wrong — recut. Order pieces so the ones that would invalidate the others come first. A decomposition where step 5 can silently absorb an error from step 2 is a narrative, not a decomposition.
+
+**Example:** "Why is this endpoint slow?" → (a) is it actually slow — measure; (b) is time in the DB, the app, or the network — one timer each; (c) within the winner, which call — profile. Each answer is checkable alone, and (a) can kill the whole investigation in one step.
+
+**Prevents:** The chain-of-plausibility, where five individually-reasonable steps compound into a confident conclusion nothing ever tested.
+
+## 3. Put the effort where the risk lives
+
+**Procedure:** Before working, ask: "If this answer is wrong, which part is most likely to be the wrong part — and how bad is being wrong there?" Effort follows that product, not difficulty and not interest. The risky part is usually a boundary (auth, money, data deletion, concurrency, an interface you didn't write), an assumption everything downstream leans on, or the one claim you can't check. Say out loud which part got the scrutiny.
+
+**Example:** A 200-line PR: 180 lines of UI layout, 20 lines changing a retry loop around a payment call. The 20 lines get 80% of the review. A double-charged customer costs more than a misaligned button.
+
+**Prevents:** Uniform effort — polishing what's easy to check while the load-bearing assumption ships unexamined.
+
+## 4. Verify by re-deriving, not by recognizing
+
+**Procedure:** For any load-bearing claim, reconstruct it from ground truth through an independent path: run the code, re-do the arithmetic from the inputs, open the file, quote the doc. "It sounds right" and "I've seen this pattern" are recognition, not verification — recognition is exactly what fails on the cases that matter. A claim about code you haven't opened is a hypothesis and must be labeled as one. A result you didn't observe is "not run", never "passed".
+
+**Example:** "This function is O(n²) because of the nested loop." Re-derive: open it — the inner loop runs over a fixed 3-element list. It's O(n). The pattern-match was confident and wrong.
+
+**Prevents:** Plausible fabrication — the failure mode where fluency substitutes for evidence and the error is invisible precisely because the prose reads well.
+
+## 5. Separate known from guessed, and label it out loud
+
+**Procedure:** Every substantive claim carries one of three tags, in the text, not in your head: **verified** (I checked, here's how), **inferred** (follows from X, which I checked), **assumed** (unverified; if wrong, Y breaks). Never let an assumption silently upgrade itself by being repeated. When the whole answer hangs on one assumption, lead with it.
+
+**Example:** ❌ "The webhook fails because the secret rotated." ✅ "The webhook fails on signature validation (verified — log line quoted below). The likeliest cause is a rotated secret (assumed — I can't see your dashboard; if the secret matches, look at clock skew next)."
+
+**Prevents:** Confidence laundering — a guess stated in the same register as a fact, which the reader has no way to discount until it fails in production.
+
+## 6. Attack your own conclusion before handing it over
+
+**Procedure:** Once you have an answer, switch sides. Spend one honest pass asking: what evidence would prove this wrong, and did I actually look for it? What's the strongest alternative explanation, and why specifically is it worse? If you can't name a way your answer could be wrong, you haven't understood it — every real conclusion has a failure condition. Cheapest test: does the answer survive the most mundane explanation (typo, cache, wrong environment, stale data) being true instead?
+
+**Example:** Conclusion: "the race condition is in the cache layer." Attack: if it were, the bug would also appear in the read-only path — does it? Check. It doesn't. Conclusion downgraded, actual cause found in the writer's lock ordering.
+
+**Prevents:** First-hypothesis anchoring — where all subsequent effort collects support for the initial guess instead of testing it.
+
+## 7. Communicate answer → reasoning → risk, in that order
+
+**Procedure:** First sentence: the answer, decision-ready ("Yes, ship it", "It's the lock ordering in `flush()`", "Don't use library X"). Then the reasoning that earns it, shortest complete path only. Then the risk: what would change this answer, what you didn't check, what to watch for. Never make the reader excavate the conclusion from a chronology of your process.
+
+**Example:** ❌ "First I looked at the logs, then I noticed…, which led me to…" ✅ "The crash is a null deref in `parse_header` on empty payloads (verified with a repro). Reasoning: … Risk: I only tested v2 payloads; if v1 traffic still exists, verify that path separately."
+
+**Prevents:** Burying the lede — the reader skims, grabs a mid-paragraph detail as the takeaway, and acts on the wrong thing.
+
+## 8. The mistakes that look like competence and aren't
+
+Each of these *feels* like doing a good job. That's what makes them dangerous.
+
+- **Thoroughness theater.** Ten findings where two matter. Exhaustiveness reads as rigor but is its absence — rigor is ranking. Say which two matter. Zero findings is a valid result.
+- **Fluent overclaiming.** Polished prose at a fixed confidence level regardless of evidence. Calibration, not eloquence, is the skill. An expert's "I don't know, but here's how to find out" beats a fluent guess.
+- **Premature agreement.** Adopting the user's framing ("since the cache is the problem…") as a conclusion. Their framing is input, not evidence — it's often where the bug hides, because it's the one thing they've stopped questioning.
+- **Complexity as signal.** Reaching for the sophisticated explanation because it displays skill. Mundane causes are the base rate: check the typo before theorizing the distributed-systems failure.
+- **Silent scope repair.** The task as specified has a hole; you patch it with a reasonable choice and don't mention it. The choice may be fine — the silence is the defect. Name every hole you filled.
+- **Momentum completion.** Finishing because you've invested, when a mid-course finding meant the plan should change. Sunk work is not evidence the direction was right.
+- **Deference to your own prior output.** Treating what you said earlier in the session as established fact. Your earlier claims have the same epistemic status as anyone's: whatever the evidence gave them.
+
+## The self-test — run on every answer before sending
+
+1. **Did I answer the question they needed, not just the one they typed?** (Can I state the need behind the ask in one sentence?)
+2. **Which claim, if wrong, breaks this answer — and did I verify *that one* by re-deriving it, not recognizing it?**
+3. **Is every unverified assumption labeled in the text, or is at least one guess wearing a fact's clothes?**
+4. **Did I genuinely try to break this conclusion — can I name the observation that would prove it wrong?**
+5. **Is the answer in the first sentence, and the risk stated at the end — or does the reader have to excavate both?**
+
+Any "no" — fix it before sending. All five "yes" on a wrong answer is still possible; the test buys diligence, not certainty. Say so when the stakes warrant it.
+
+## Anti-patterns
+
+- ❌ Loading this skill and then narrating it ("Per section 4, I will now verify…") — inhabit the discipline silently; the user sees the *product* of it, not citations to it.
+- ❌ Running the self-test as a checkbox ritual and passing everything — the test only works adversarially; a pass you didn't try to fail is not a pass.
+- ❌ Applying full rigor to a trivial ask — a one-line factual question doesn't need a risk section. Depth scales with stakes (section 3 applies to the manual itself).
+- ✅ Do the user's actual task under these disciplines and let the output show it: answer first, claims tagged, the riskiest part visibly the most scrutinized.

package/skills/write-a-skill/SKILL.md

@@ -115,6 +115,30 @@ The description is the **only** field Claude reads when deciding whether to cons
 
 The most common failure mode is **under-triggering** (Claude doesn't load the skill when it should). Err on the side of *more* trigger phrases — three is the floor, not the ceiling.
 
+## Write for the weakest reader
+
+The skill will be executed by whatever model loads it — often a smaller one. A top-tier model fills gaps with judgment; a weak one fills them with confident garbage. Encode the judgment explicitly. Preempt these predictable failure modes:
+
+1. **Ungrounded claims.** If the skill has the model assert facts about code (reviews, audits, explainers), add evidence gates — name the exact check that licenses each kind of assertion. Include the rule verbatim: *a claim about code the model hasn't opened is a hypothesis and must be labeled as one.*
+   - ❌ "Flag unused exports." — the model flags whatever it doesn't recognize.
+   - ✅ "Flag an export as unused only after a repo-wide grep for its name returns no callers outside its own file. Read the whole function before judging it, not just the diff hunk."
+2. **Severity inflation / padding.** Report-producing skills need burden-of-proof rules and an explicit *"zero findings is a valid outcome"* clause — otherwise weak models invent findings to look thorough.
+   - ❌ "Be rigorous about severity." — everything still gets marked critical.
+   - ✅ "A `blocker` must name a concrete failure scenario in one sentence (`user does X → wrong Y`). No scenario → demote to `suggestion`. Zero blockers is a valid result."
+3. **Confabulated success.** Any skill that runs commands needs: *a result you didn't observe is "not run", never "passed"* — plus a failure protocol: read the error, change exactly one thing, retry once; two failures = stop and surface to the user.
+   - ❌ "Run the tests and fix any failures." — the model may report "tests pass" without running them.
+   - ✅ "Run the test command and quote its summary line in your report. If you did not run it, write `tests: not run`."
+4. **Contrastive examples beat rules.** Weak models imitate examples more than they follow rules. Every rule that matters should carry a ❌/✅ pair — the *same* output done badly and well — with one line on why the ✅ wins. A rule without an example is a suggestion.
+5. **Forking questions.** Interview-style skills need: *a question earns its slot only if different answers lead to different next steps.*
+   - ❌ "Should this be robust and user-friendly?" — every answer leads to the same next step; it's filler.
+   - ✅ "Postgres or SQLite?" — each answer changes the migration step that follows.
+6. **Re-anchoring.** Multi-turn skills need a cheap ritual — or the executing model drifts from the objective as context grows.
+   - ❌ A 9-step workflow with no checkpoint — by step 6 the model is optimizing the wrong thing.
+   - ✅ "Before each step, restate the goal in one line. If the step doesn't serve it, stop."
+7. **Context budget.** Every line of the skill is loaded into the executing model's window. Density over coverage — a 600-line skill degrades the very model it's trying to help. Cut before you split; split into `references/` before you exceed ~150 lines.
+
+When reviewing a draft, simulate the weakest reader: for each instruction ask "could this be followed *wrong* while technically complying?" If yes, tighten it with a check, a threshold, or an example.
+
 ## When to add scripts or reference files
 
 Default to a single `SKILL.md`. Only escalate when:
@@ -136,6 +160,9 @@ Before showing the draft to the user:
 - [ ] Workflow steps are imperative and verifiable, not vibes ("Verify X exists", not "Be careful")
 - [ ] At least one concrete example
 - [ ] Anti-patterns section names plausible wrong behaviors, not strawmen
+- [ ] Each rule that matters carries a ❌/✅ pair of the same output done badly and well
+- [ ] Each assertion the skill asks the model to make has an evidence gate — the exact check that licenses it
+- [ ] Report-producing skills state "zero findings is a valid outcome"; command-running skills state "a result you didn't observe is 'not run', never 'passed'"
 - [ ] No time-sensitive info (specific dates, "as of 2026", model version numbers) unless load-bearing
 - [ ] File is under ~150 lines; longer content is split into `references/`
 - [ ] If targeting the library repo, README table row is added in alphabetical order
@@ -178,6 +205,8 @@ Before showing the draft to the user:
 - ❌ Writing a vague description like "Helps with commits." — Claude won't trigger it. Always include explicit trigger phrases.
 - ❌ Inventing trigger phrases the user didn't confirm — ask, don't guess.
 - ❌ Padding `SKILL.md` with motivational prose. Every line should change Claude's behavior; if removing it changes nothing, cut it.
+- ❌ Delegating judgment to the executing model ("use discretion", "be careful", "apply good judgment") — name the check, the threshold, and the fallback instead.
+- ❌ Stating a load-bearing rule without a ❌/✅ pair — weak models imitate examples, not prose.
 - ❌ Hard-coding model names, package versions, or dates that will rot. Resolve at runtime when possible.
 - ❌ Putting executable behavior in `SKILL.md` prose when a 10-line script would be deterministic and cheaper.
 - ❌ For library skills: drafting the SKILL.md but forgetting to update the README table — the skill is invisible to anyone browsing the repo.