@dennisrongo/skills 0.2.0 → 0.3.0

package/README.md

@@ -92,16 +92,17 @@ node bin/claude-skills.js list
 
 | Skill | What it does |
 |---|---|
-| [`code-review`](./skills/code-review/SKILL.md) | Production-readiness review of **uncommitted** working-tree changes (staged + unstaged). Hunts DRY violations, dead code, leaky abstractions, premature abstraction, magic values, missing error handling, debug residue, missing migrations / flags / logs, and other common best-practice gaps — prioritized correctness → DRY/design → tests → security → performance → production-readiness → readability. Auto-detects and runs the project's tests and build (`npm`, `pytest`, `dotnet`, `go`, `cargo`, `Makefile`, monorepo orchestrators) and gates the verdict on them being green. **Never edits code unprompted** — produces a categorized report (`blocking` / `suggestion` / `nit` / `praise`) with `file:line` citations, then asks per-finding before fixing. Distinct from [`pr-review`](./skills/pr-review/SKILL.md), which scopes to committed branch work. Triggers on "code review", "review the diff", "is this production ready", "DRY check", or `/code-review`. |
+| [`code-review`](./skills/code-review/SKILL.md) | Production-readiness review of **uncommitted** working-tree changes (staged + unstaged). Hunts DRY violations, dead code, leaky abstractions, premature abstraction, magic values, missing error handling, debug residue, missing migrations / flags / logs, and other common best-practice gaps — prioritized correctness → DRY/design → tests → security → performance → production-readiness → readability. On non-trivial diffs, convenes a **lens council**: parallel `Explore` sub-agents reviewing through distinct lenses (correctness / design / security / tests / production-readiness), followed by an **adversarial critique round** that challenges each lens's blocking flags against context from the others — false positives demoted, contradictions surfaced for the user, multi-lens findings promoted. Small diffs skip the council. Auto-detects and runs the project's tests and build (`npm`, `pytest`, `dotnet`, `go`, `cargo`, `Makefile`, monorepo orchestrators) and gates the verdict on them being green. **Never edits code unprompted** — produces a categorized report (`blocking` / `suggestion` / `nit` / `praise`) with `file:line` citations, then asks per-finding before fixing. Distinct from [`pr-review`](./skills/pr-review/SKILL.md), which scopes to committed branch work. Triggers on "code review", "review the diff", "is this production ready", "DRY check", or `/code-review`. |
+| [`codebase-explainer`](./skills/codebase-explainer/SKILL.md) | Produce a durable onboarding artifact for a repo — writes `ONBOARDING.md` (or `docs/ONBOARDING.md` if `docs/` exists) with a tight **read this first** minimum, system overview, dependency map (top-level prod deps + how each is actually used in *this* codebase, with key call site), startup flow (entry point → bootstrap → config), auth flow (or an explicit "no auth detected" when there isn't one), and the 5–15 important files — every claim backed by a `file:line` citation. Walks the repo with **parallel Explore sub-agents** to stay context-safe on big projects, refreshes an existing `ONBOARDING.md` in place instead of rewriting from scratch, and is opinionated about what *not* to include (no dev/test/types deps, no 40-file "important files" lists, no fabricated auth flows, no dates that rot). Built for revisiting a project after months away — and for new teammates landing in an unfamiliar repo. Composes with [`improve-codebase-architecture`](./skills/improve-codebase-architecture/SKILL.md) when shallow-module clusters surface and [`handoff`](./skills/handoff/SKILL.md) for session-level state. Triggers on "explain this codebase", "onboard me", "give me a tour", "where do I start", "I haven't looked at this in months", or `/codebase-explainer`. |
 | [`conventional-commits`](./skills/conventional-commits/SKILL.md) | Write git commit messages that follow the [Conventional Commits](https://www.conventionalcommits.org/) spec (`feat`, `fix`, `chore`, `docs`, …), auto-prefixed with the ticket number from the current branch (e.g. `feature/12345-...` → `#12345`) and a project tag (`API` / `CLIENT` / `CONSOLE` / `DB`) when detectable from the diff. Both prefixes are omitted when they don't apply. Triggers on commit-message requests. |
-| [`diagnose`](./skills/diagnose/SKILL.md) | Disciplined diagnosis loop for hard bugs and performance regressions — reproduce → minimise → hypothesise → instrument → fix → regression-test. Forces a fast, deterministic feedback loop before any guessing, generates 3–5 ranked falsifiable hypotheses, uses tagged `[DEBUG-...]` instrumentation that's trivially cleaned up, and ends with a post-mortem on what would have prevented the bug. Triggers on "diagnose this" / "debug this" / bug reports / flaky tests / perf regressions. |
+| [`diagnose`](./skills/diagnose/SKILL.md) | Disciplined diagnosis loop for hard bugs and performance regressions — reproduce → minimise → hypothesise → instrument → fix → regression-test. Forces a fast, deterministic feedback loop before any guessing. On non-trivial cases, Phase 3 convenes a **hypothesis council**: parallel `Explore` sub-agents — one per candidate hypothesis — each defending its case with falsifiable predictions and `file:line` evidence from the actual codebase, followed by a cross-examination round that drops defenders who couldn't find supporting evidence and ranks the survivors. Trivial bugs skip the council and use 1–2 inline hypotheses. Uses tagged `[DEBUG-...]` instrumentation that's trivially cleaned up, and ends with a post-mortem on what would have prevented the bug. Triggers on "diagnose this" / "debug this" / bug reports / flaky tests / perf regressions. |
 | [`dotnet-onion-api`](./skills/dotnet-onion-api/SKILL.md) | Scaffold a new .NET solution (Web API + Worker microservices) using ONION architecture and EF Core, codifying battle-tested layered patterns and explicitly removing common legacy pitfalls (sproc-centric repos with reflection, EF6 on netstandard2.1, polling console workers, mutable base-service state, missing `CancellationToken`). Three modes — full solution scaffold, add-a-feature slice, add-a-worker microservice. Resolves TFM and NuGet versions at scaffold time (not hard-coded). |
 | [`grill-with-docs`](./skills/grill-with-docs/SKILL.md) | Interview-driven design review. Stress-tests a plan, RFC, or feature idea against the project's existing domain model and documented decisions — one question at a time with `AskUserQuestion`, sharpening fuzzy terminology and surfacing contradictions with the codebase. Updates `CONTEXT.md` (glossary) inline as terms resolve and writes ADRs to `docs/adr/` only when the decision is hard to reverse, non-obvious, and had real trade-offs. Writes no production code — composes with [`plan-and-build`](./skills/plan-and-build/SKILL.md) for the implementation handoff. Triggers on "grill me", "stress-test this plan", "challenge this design", "/grill-with-docs", or a pasted RFC. |
 | [`handoff`](./skills/handoff/SKILL.md) | Capture a session hand-off before context runs out — writes a dated `.claude/handoffs/*.md` (objective, progress, decisions, files, open issues, ready-to-paste next-session prompt) plus a lightweight memory pointer so a fresh Claude session can resume cleanly. |
 | [`improve-codebase-architecture`](./skills/improve-codebase-architecture/SKILL.md) | Surface architectural friction and propose **deepening opportunities** — refactors that collapse clusters of shallow modules into one deep module with a real seam. Walks the codebase with an Explore sub-agent, applies the **deletion test** to suspected pass-throughs, presents numbered candidates (files / problem / solution / benefits) using `CONTEXT.md` for the domain and a strict architecture glossary (module / interface / seam / depth / leverage / locality) for the structure, then drops into a grilling loop with optional parallel sub-agent interface design ("Design It Twice"). Updates `CONTEXT.md` inline as new concepts get named and offers an ADR only when a rejection is load-bearing. Composes with [`grill-with-docs`](./skills/grill-with-docs/SKILL.md) for glossary + ADR discipline and [`plan-and-build`](./skills/plan-and-build/SKILL.md) for the implementation handoff. Writes no production code. Triggers on "improve architecture", "architecture review", "find refactoring / deepening opportunities", "find shallow modules", "make this more testable", or `/improve-codebase-architecture`. |
 | [`nextjs-app-router`](./skills/nextjs-app-router/SKILL.md) | Scaffold a new Next.js (App Router) **fullstack** app — TypeScript, **NextAuth (Auth.js v5)**, **Prisma + PostgreSQL**, Route Handlers as the backend, Redux Toolkit + RTK Query, Tailwind + shadcn/ui (Radix), React Hook Form + Zod. **API-driven by deliberate choice**: pages are `'use client'`, all data flows UI → RTK Query → `/api/**` Route Handlers → Prisma. No `fetch()` in server components, no Server Actions, no async `page.tsx`. Confirms the database (Postgres + Prisma) and NextAuth providers with the user before writing files. Forbids the usual pitfalls (custom JWT cookies alongside NextAuth, multiple `createApi`/`PrismaClient` instances, `serializableCheck: false`, `@ts-ignore`, mixed `moment`/`date-fns`, `styled-components` alongside Tailwind, case-sensitive folder dupes, `dangerouslySetInnerHTML` without sanitization, Route Handlers that skip `requireSession()` or trust client-sent user IDs, `prisma db push` in CI). Three modes — full project scaffold, add-a-feature slice (page + form + Route Handler + Zod schema + RTK Query endpoints + Prisma model), add-an-API-slice. Resolves package versions at scaffold time (not hard-coded). |
-| [`plan-and-build`](./skills/plan-and-build/SKILL.md) | Plan-first feature builder. Grills the user about the feature (à la `grill-with-docs`) until the design is unambiguous, detects the project's stack and conventions, presents a plan, and gates on `ExitPlanMode` approval before writing any code. Builds TDD-first with NUnit when a .NET API changes — appending to the matching test class if one already exists rather than forking a parallel one — reuses existing patterns, keeps comments minimal, and generates EF Core / migration files **without ever** running `dotnet ef database update` or any DDL/SQL against the user's database. Triggers on "build/add/implement a feature", "/plan-and-build", or a pasted feature spec. |
-| [`pr-review`](./skills/pr-review/SKILL.md) | Conduct a structured PR / diff review prioritized correctness → design → tests → security → performance → readability, with categorized feedback (`blocking` / `suggestion` / `question` / `nit` / `praise`). |
+| [`plan-and-build`](./skills/plan-and-build/SKILL.md) | Plan-first feature builder. Grills the user about the feature (à la `grill-with-docs`) until the design is unambiguous, detects the project's stack and conventions, presents a plan, and gates on `ExitPlanMode` approval before writing any code. When Phase 3 hits a genuine design fork (service-layer vs. CQRS, new table vs. nullable columns, sync vs. background job, etc.) and Phase 2 didn't settle it, runs **Design It Twice**: two parallel sub-agents each draft the BEST plan for one side of the named axis, then an inline debate names three wins for each and recommends one — the user sees a single recommended plan with a one-line "considered alternative" note so they can redirect with one sentence. Skipped when an existing pattern in the repo already dictates the approach. Builds TDD-first with NUnit when a .NET API changes — appending to the matching test class if one already exists rather than forking a parallel one — reuses existing patterns, keeps comments minimal, and generates EF Core / migration files **without ever** running `dotnet ef database update` or any DDL/SQL against the user's database. Triggers on "build/add/implement a feature", "/plan-and-build", or a pasted feature spec. |
+| [`pr-review`](./skills/pr-review/SKILL.md) | Structured review of a local branch, **grouped per `#NNN` task** referenced in commit messages, prioritized correctness → design → tests → security → performance → readability, with categorized feedback (`blocking` / `suggestion` / `question` / `nit` / `praise`). On non-trivial tasks, convenes a **per-task lens council**: parallel `Explore` sub-agents through distinct lenses (correctness / design / security / tests) on that task's diff only, followed by an **adversarial critique round** that demotes false-positive blockers when another lens defuses them, surfaces contradictions as `question` items for the user, and promotes findings raised by multiple lenses independently. Small tasks skip the council. The council never crosses task boundaries — each `#NNN` gets its own verdict. Triggers on "review my PR", "review the diff", "review my branch", or `/pr-review`. |
 | [`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). |
 | [`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". |
 
@@ -228,33 +229,71 @@ npx --yes github:dennisrongo/claude-skills install --all --force
 
 ## Releasing
 
-Releases are published to npm automatically by [`.github/workflows/publish.yml`](./.github/workflows/publish.yml) when a GitHub Release is published. The package ships with [npm provenance](https://docs.npmjs.com/generating-provenance-statements) — npm verifies it was built by this repo's Actions workflow.
-
-One-time setup:
-
-1. Create an automation-scoped `NPM_TOKEN` at https://www.npmjs.com/settings/<user>/tokens (use a "Granular Access Token" or "Automation" token).
-2. Add it to the repo as a secret: **Settings → Secrets and variables → Actions → New repository secret**, name `NPM_TOKEN`.
-3. If you ever rename the package, confirm the new name is free: `npm view <name>`. The current scoped name `@dennisrongo/skills` lives under your npm user/org — `npm publish --access public` will create it on first publish.
-
-Cutting a release:
+Releases are published to npm automatically by [`.github/workflows/publish.yml`](./.github/workflows/publish.yml) **when a GitHub Release is published**. The package ships with [npm provenance](https://docs.npmjs.com/generating-provenance-statements) — npm verifies it was built by this repo's Actions workflow.
+
+### Cutting a release — step by step
+
+Run these from a clean working tree on `main`, in this order.
+
+1. **Commit and push your work first.** The release is cut from the tip of `main`; nothing uncommitted gets shipped.
+   ```bash
+   git status            # must be clean
+   git push origin main
+   ```
+2. **Pick the bump.** Follow semver (pre-1.0: still treat new features as `minor`):
+   - `patch` — bug fix in an existing skill, doc tweak, CLI fix.
+   - `minor` — new skill, materially new behavior in an existing skill, new CLI flag.
+   - `major` — removal or rename of a skill / CLI command, breaking change to install layout.
+3. **Bump the version + create the tag.**
+   ```bash
+   npm version <patch|minor|major>
+   # creates a "vX.Y.Z" commit and a matching git tag
+   ```
+4. **Push the bump commit and the tag together.**
+   ```bash
+   git push --follow-tags
+   ```
+5. **Create the GitHub Release** — this is the step that **triggers the npm publish workflow**.
+   ```bash
+   gh release create "v$(node -p "require('./package.json').version")" --generate-notes
+   ```
+6. **Watch the workflow run.**
+   ```bash
+   gh run watch           # interactive, exits when done
+   # or
+   gh run list --workflow=publish.yml --limit 1
+   ```
+7. **Verify the publish.** Once the run is green:
+   ```bash
+   npm view @dennisrongo/skills version    # should match the new tag
+   npx @dennisrongo/skills@latest list     # smoke test
+   ```
+
+If the workflow fails, fix forward — don't reuse a published version number. npm rejects republishing the same version, so the next attempt needs a fresh bump.
+
+### What the workflow does
+
+`.github/workflows/publish.yml` runs on `release: published` and:
+
+1. Checks out the tag.
+2. Asserts `package.json` version matches the release tag (fails fast on mismatch).
+3. Runs `npm test`.
+4. Runs `npm publish --provenance --access public`.
+
+Both invocation forms work after publish:
 
 ```bash
-# Bump version (creates a commit + tag)
-npm version patch   # or minor / major
-
-# Push the commit and tag
-git push --follow-tags
-
-# Create a GitHub Release pointing at the new tag — the workflow takes over from there.
-gh release create "v$(node -p "require('./package.json').version")" --generate-notes
+npx @dennisrongo/skills install                 # via npm (recommended)
+npx github:dennisrongo/claude-skills install    # latest commit on main
 ```
 
-The workflow checks `package.json` version matches the release tag, runs tests, then publishes with `--provenance`. After publishing both invocation forms work:
+### One-time setup (already done for this repo)
 
-```bash
-npx @dennisrongo/skills install                 # via npm
-npx github:dennisrongo/claude-skills install    # still works, latest main
-```
+Keep this for reference if the package ever moves or gets forked:
+
+1. Create an automation-scoped `NPM_TOKEN` at https://www.npmjs.com/settings/<user>/tokens (use a "Granular Access Token" or "Automation" token).
+2. Add it to the repo as a secret: **Settings → Secrets and variables → Actions → New repository secret**, name `NPM_TOKEN`.
+3. If you ever rename the package, confirm the new name is free: `npm view <name>`. The current scoped name `@dennisrongo/skills` lives under your npm user/org — `npm publish --access public` will create it on first publish.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dennisrongo/skills",
-  "version": "0.2.0",
+  "version": "0.3.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/code-review/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: code-review
+description: Production-readiness code review of **uncommitted** working-tree changes (staged + unstaged). Hunts DRY violations, dead code, leaky abstractions, missing error handling, and other common best-practice gaps; auto-detects and runs the project's tests and build; reports findings categorized `blocking` / `suggestion` / `nit` and **never edits code without permission** — recommendation first, ask, then fix. On non-trivial diffs, spawns a **lens council**: parallel `Explore` sub-agents reviewing through distinct lenses (correctness / design / security / tests / production-readiness), then an adversarial critique round that challenges each lens's blocking flags against context from the others — false positives get demoted, contradictions get surfaced for the user to adjudicate. Small diffs skip the council. Use this skill whenever the user says "code review", "review my code", "review the diff", "check my uncommitted changes", "is this production ready", "ready to ship", "DRY check", "clean up duplication", or "/code-review" — even if they don't explicitly say "code review skill". Distinct from `pr-review` (which scopes to committed branch work grouped by `#NNN`): this skill scopes to the working tree and gates on tests + build green.
+---
+
+# Code Review
+
+Review the uncommitted changes in the working tree against DRY and common software-engineering best practices, verify the project still builds and its tests still pass, and surface findings as recommendations the user can act on — **without editing code unprompted**.
+
+## When to use this skill
+
+- "code review" / "review my code" / "review the diff"
+- "check my uncommitted changes" / "is this production ready" / "ready to ship"
+- "DRY check" / "clean up duplication"
+- `/code-review`
+
+Do **not** auto-trigger when the user is asking for a PR / committed-branch review — defer to [`pr-review`](../pr-review/SKILL.md) for that. The dividing line is **committed vs. uncommitted**.
+
+## Hard rule: recommend, don't refactor
+
+If you find issues, **do not start editing**. Produce the findings report first. After delivering it, ask the user, per issue or per batch: *"Want me to fix #N?"* — and wait for an explicit yes before touching code. If the user pre-authorizes the whole batch ("fix them all"), proceed; otherwise default to ask-per-fix.
+
+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.
+
+## Workflow
+
+1. **Snapshot the diff.** Run in parallel:
+   - `git status --short` — see what's modified, staged, untracked.
+   - `git diff` — unstaged changes.
+   - `git diff --staged` — staged changes.
+   - `git diff <base>...HEAD` is **out of scope** here — that's `pr-review`'s job.
+2. **Understand intent.** Read the diff top-to-bottom once. If the *why* isn't obvious from context, ask the user one focused question before reviewing — "is this correct" is unanswerable without intent.
+3. **Detect test + build commands.** Inspect repo manifests in parallel and infer commands:
+   - `package.json` → `npm test`, `npm run build` (or `pnpm` / `yarn` if the lockfile says so)
+   - `pyproject.toml` / `pytest.ini` → `pytest`, plus `python -m build` or project-specific
+   - `*.csproj` / `*.sln` → `dotnet build`, `dotnet test`
+   - `go.mod` → `go build ./...`, `go test ./...`
+   - `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.
+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.
+   Earlier categories outrank later ones — a correctness bug makes a readability nit irrelevant.
+6. **Map findings to the diff.** Every finding cites `file:line` so the user can jump to it.
+7. **Categorize each finding** as `blocking` / `suggestion` / `nit` / `praise` (see [Categories](#categories)).
+8. **Produce the report** in the [Output format](#output-format).
+9. **Offer to fix.** After the report, list the fix-able findings by number and ask which to apply. Wait for confirmation. Then fix only the approved ones, one commit-worthy change at a time, and re-run tests after. When applying fixes, follow the [Code rules when applying fixes](#code-rules-when-applying-fixes) below.
+
+## Code rules when applying fixes
+
+These rules govern the fix-application phase only — they don't change the report itself.
+
+- **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. One short line max — no multi-line comment blocks, no multi-paragraph docstrings. If the fix needs a comment to be understandable, the fix probably needs better names instead.
+- **No drive-by edits.** Touch only what the approved finding requires. If you spot something else worth fixing, surface it as a *new* finding in a follow-up report — don't bundle it in.
+- **Match the project's formatting.** Don't reformat unrelated code in the diff.
+- **No `// removed`, `// was: X` trails.** If you deleted something, delete it. Git history is the audit log.
+
+## Categories
+
+- **`blocking`** — must fix before ship: bug, broken contract, security hole, build/test failure, missing migration, hard-coded secret.
+- **`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.
+
+Lead each finding with the *why*. "This swallows the exception so a failure here is silently lost" beats "add error handling".
+
+## What to look for
+
+Priority order — review top-to-bottom, stop wasting tokens on lower categories once a higher one is on fire.
+
+### 1. Correctness
+- Off-by-one in loops and slicing
+- Null / undefined / empty-collection handling at boundaries
+- Concurrent access without synchronization; race conditions in async code
+- Error paths that swallow exceptions or log-and-continue when they shouldn't
+- Default values that silently change behavior
+- Floating-point comparisons with `==`
+- Timezone / DST / locale assumptions
+
+### 2. DRY and design
+This is the user-emphasized lens — apply it explicitly.
+- **Duplication that should be unified** — same logic in 2+ places, copy-pasted blocks, parallel switch/if-else ladders, the same regex written twice.
+- **Premature abstraction** (the inverse trap) — a "shared helper" with one caller, configurable in ways nobody uses. **YAGNI** wins; three similar lines beats a wrong abstraction.
+- **Single Responsibility** — functions doing two unrelated things, classes mixing concerns.
+- **Leaky abstractions** — implementation details bleeding through an interface (e.g. ORM types in a domain API).
+- **Tight coupling** that will be painful to undo; circular dependencies.
+- **State that should live elsewhere** — module-level mutable state, globals smuggled in via singletons.
+- **Public API changes** that aren't backwards-compatible without a migration note.
+- **Magic numbers / magic strings** — name them.
+- **Composition over inheritance** where inheritance is being used as code-reuse, not for "is-a".
+
+### 3. Tests
+- Tests that pass even when the code is broken (assertion-free, over-mocked, snapshot-only).
+- Missing edge cases: empty inputs, max sizes, unicode, negative numbers, timezones, concurrent calls.
+- Flaky-by-design tests (`sleep`, ordering assumptions, network).
+- New behavior in the diff with **no new test** — call it out.
+- Test names that describe *what runs* instead of *what's verified*.
+
+### 4. Security
+- User input flowing into shell, SQL, HTML, file paths, or `eval` without escaping/parameterization.
+- Secrets in code, logs, error messages, or commit-able files.
+- Authn / authz checks missing on new endpoints or new entry points.
+- Crypto: hand-rolled, weak algos (`md5`, `sha1` for security use), hardcoded keys/IVs.
+- `console.log` / `print` / `Debug.WriteLine` of PII or tokens.
+- Unsafe deserialization of untrusted input.
+
+### 5. Performance
+- N+1 queries inside loops.
+- Unbounded memory growth — caches without eviction, accumulating arrays, recursive growth.
+- Synchronous I/O / blocking calls in hot paths or async contexts.
+- Repeated work that could be hoisted out of a loop.
+- O(n²) where O(n) is easy.
+
+### 6. Production-readiness (working-tree-specific lens)
+- **Debug residue** — `console.log`, `print`, `TODO: remove`, `// debug`, commented-out blocks, scratch files.
+- **Logging** — new code path with no log line at all, *or* spammy logs in a hot path.
+- **Observability** — new failure mode with no metric / no trace.
+- **Config** — new env var without a default and without docs / `.env.example`.
+- **Migrations** — schema change with no migration, or a migration without a rollback story.
+- **Error messages** — user-facing errors leaking stack traces, internal paths, or DB error strings.
+- **Feature flags** — new behavior shipped unflagged when the project uses flags.
+- **Backward compatibility** — breaking a wire format, DB column, or public API without a deprecation path.
+
+### 7. Readability
+- Naming: variables that say *what* (`data`, `result`) instead of *what for*.
+- Function length / nesting depth — extract when it stops fitting in your head.
+- Comments: only when *why* is non-obvious; not narration of *what*.
+- Dead code, unused imports, unused exports.
+
+### 8. Style
+Only mention if the project has no formatter / linter. Otherwise trust the tools.
+
+## Lens council (for non-trivial diffs)
+
+A single pass through the priority list anchors on whatever you saw first. For non-trivial diffs, run the lenses **in parallel** and then have them critique each other before publishing findings.
+
+### When to convene the council
+
+- Diff is ≥ ~100 lines changed, **or** touches ≥ 5 files, **or** edits security-sensitive paths (auth, crypto, input validation, SQL/shell/HTML sinks, file paths from user input).
+- Or you've already spotted contradictions on first read ("this looks broken / no it's fine because…") — the council resolves them deterministically.
+
+Otherwise stay single-pass. The council is overhead on a 20-line change.
+
+### Lenses
+
+Spawn one sub-agent per lens. Default set (skip lenses that don't apply — e.g. no schema changes → no migration sub-lens within prod-readiness):
+
+| Lens | Looks for | Aligns with |
+|---|---|---|
+| **Correctness** | Off-by-one, null/undefined, race conditions, swallowed errors, default-value behaviour shifts, tz/locale assumptions | §1 |
+| **Design / DRY** | Duplication that should unify, premature abstraction, single-responsibility violations, leaky abstractions, tight coupling, magic values, public-API breakage | §2 |
+| **Security** | Untrusted input into sinks (shell/SQL/HTML/path/`eval`), secrets in code or logs, missing authn/authz, weak crypto, unsafe deserialization | §4 |
+| **Tests** | Assertion-free / over-mocked / snapshot-only tests, missing edge cases, flaky-by-design tests, new behaviour with **no** test, test names that don't describe verification | §3 |
+| **Production-readiness** | Debug residue, missing/spammy logging, no observability on new failure modes, undocumented env vars, schema change without migration, error messages leaking internals, missing feature flag, wire/DB breakage without deprecation | §6 |
+
+Performance (§5), readability (§7), and style (§8) usually roll into Design — only spawn a dedicated lens for them if the diff is genuinely perf-sensitive or the project has no linter.
+
+### How to run it
+
+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."
+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.
+   - **Surface contradictions.** Correctness flags a missing null check, but Security found the caller validates upstream → call it out as a *question* for the user, not a flag, and link both citations.
+   - **Merge near-duplicates** across lenses (e.g. Design and Tests both noticed the new branch has no coverage — merge into one finding).
+   - **Promote** anything multiple lenses independently flagged. That's a real signal.
+4. **Publish.** Synthesize into the [Output format](#output-format). Add a footer: `Lenses run: <list>. <N> findings raised by sub-agents, <M> dropped on critique.`
+
+The user sees one clean report, not five agent transcripts. The transcripts stay internal — they were the deliberation.
+
+## Output format
+
+```
+# Code review — uncommitted changes
+
+**Files changed:** <N> (<S staged>, <U unstaged>, <X untracked>)
+
+**Build:** ✅ passed / ❌ failed / ⚠️ not detected
+**Tests:** ✅ passed (<N>/<N>) / ❌ failed (<F> failing) / ⚠️ not detected
+<paste relevant failing output, trimmed>
+
+---
+
+## Verdict
+**Ship / Fix blockers first / Build broken**
+
+<one-paragraph summary of the change and overall state>
+
+---
+
+## Blockers
+
+### B1. <short title> — `path/to/file.ext:42`
+**Why:** <root cause / consequence>
+**Fix:** <concrete recommendation>
+
+### B2. ...
+
+## Suggestions
+
+### S1. <short title> — `path/to/file.ext:88`
+**Why:** ...
+**Fix:** ...
+
+## Nits
+- `path:line` — <one-liner>
+
+## Praise
+- <thing done well>
+
+---
+
+## Fixes I can apply
+
+If you want, I can apply any of: B1, B2, S1, S3. Which? (or "all", or "none")
+```
+
+End with the offer. Wait for the user's choice. Apply only the approved set, then re-run tests.
+
+## Examples
+
+### Example 1: Working-tree review with a build failure
+
+**User:** "do a code review on what I have so far"
+
+**Claude:**
+- Runs `git status` + `git diff` + `git diff --staged` in parallel.
+- Detects `package.json` → runs `npm test` and `npm run build`.
+- Build fails on a missing import → calls it out as `B1` with the file:line, doesn't try to fix it yet.
+- Finds two copy-pasted validation blocks → `S1` (DRY consolidation) with a sketch of the extracted helper.
+- Reports, then asks: "Want me to fix B1 and S1?"
+
+### Example 2: Pre-existing tests, new feature with no coverage
+
+**User:** "is this ready to ship?"
+
+**Claude:** Reviews diff. Tests pass but the new branch in `processOrder()` has no test. Flags as `B2` (blocking — "new behavior with no test, regression risk on next refactor"). Does **not** write the test silently; offers to write it after the report.
+
+### Example 3: User pre-authorizes fixes
+
+**User:** "review the diff and fix anything you find"
+
+**Claude:** Produces the full report first anyway, then applies fixes one at a time, re-running tests between batches. Pre-authorization doesn't skip the report — it only skips the per-fix confirmation.
+
+## Anti-patterns
+
+- ❌ Editing files during the review pass. Report first, **always**.
+- ❌ Fixing without asking, even for "obvious" issues. Obviousness is not consent.
+- ❌ Skipping the test/build run because "the diff looks fine".
+- ❌ Reporting a green build without actually running it.
+- ❌ Reviewing committed history — that's [`pr-review`](../pr-review/SKILL.md)'s job. Stop at the working tree.
+- ❌ 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`.
+- ❌ 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.
+- ❌ Dumping the per-agent transcripts into the user's report. The council is internal deliberation — the user sees the synthesized report.
+- ✅ Tests + build run, findings cited to lines, categorized, **report → ask → fix**.
+
+## Notes
+
+- If the working tree is clean, say so and stop — there's nothing to review. Don't pivot to `pr-review` without being asked.
+- If tests take a long time, run them in the background and continue the static review while they run; reconcile the report once results land.
+- This skill composes with [`conventional-commits`](../conventional-commits/SKILL.md): after fixes are approved and applied, hand the commit-message authoring to that skill rather than improvising one here.

package/skills/codebase-explainer/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: codebase-explainer
+description: Produce a durable onboarding artifact for a codebase — writes `ONBOARDING.md` (or `docs/ONBOARDING.md` if `docs/` exists) covering a "read this first" minimum, system overview, dependency map (top-level deps + how each is actually used), startup flow (entry points → bootstrap → config), auth flow (or explicit "none detected"), and 5–15 important files — every claim backed by a `file:line` citation. Walks the repo via parallel Explore sub-agents so big projects don't blow context, calls out what makes THIS codebase non-obvious (not generic framework descriptions), refreshes an existing onboarding doc instead of rewriting from scratch, and renders a condensed summary inline. Built for revisiting a project after months away and for new teammates landing in an unfamiliar repo. Use this skill whenever the user says "explain this codebase", "explain the codebase", "onboard me", "give me a tour", "tour this repo", "what does this repo do", "where do I start", "I haven't looked at this in months", "codebase overview", "read this first", or invokes `/codebase-explainer` — even if they don't name the skill.
+---
+
+# Codebase Explainer
+
+Produce a durable onboarding artifact — the document past-you wishes you'd written before stepping away from this repo for six months. Not a chat answer that disappears: a committed `ONBOARDING.md` with a tight "read this first" list, system overview, dependency map, startup flow, auth flow, and the important files. Every claim cited with `file:line`.
+
+## When to use this skill
+
+- "explain this codebase" / "explain the codebase" / "what does this repo do"
+- "onboard me" / "give me a tour" / "tour this repo" / "where do I start"
+- "I haven't looked at this in months" / "I forgot how this works"
+- "codebase overview" / "read this first" / "create an onboarding doc"
+- `/codebase-explainer` / `/onboard`
+
+Do **not** auto-trigger for:
+
+- Architecture refactor suggestions → [`improve-codebase-architecture`](../improve-codebase-architecture/SKILL.md)
+- Feature design or implementation → [`plan-and-build`](../plan-and-build/SKILL.md)
+- Bug triage → [`diagnose`](../diagnose/SKILL.md)
+- A specific diff review → [`pr-review`](../pr-review/SKILL.md) or [`code-review`](../code-review/SKILL.md)
+- Session hand-off (different artifact, session-scoped) → [`handoff`](../handoff/SKILL.md)
+
+## Workflow
+
+### 1. Detect the lay of the land (no sub-agents yet)
+
+Read root-level signals directly to scope the exploration:
+
+- **Manifests** — `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `*.csproj`, `*.sln`, `Gemfile`, `composer.json`, `pom.xml`, `build.gradle*`.
+- **Entry-point hints** — `next.config.*`, `vite.config.*`, `tsconfig.json`, `Procfile`, `Dockerfile`, `docker-compose*.yml`, `main.*`, `Program.cs`, `manage.py`.
+- **Existing docs** — `README.md`, `CONTEXT.md`, `docs/`, any `ONBOARDING.md` already present.
+- **Workspace shape** — monorepo (`pnpm-workspace.yaml`, `lerna.json`, `nx.json`, `turbo.json`) vs. single project.
+
+If an `ONBOARDING.md` already exists, this is **refresh mode**: read it first, then look for drift (new top-level deps, moved entry points, new/removed routes, auth changes) and update in place — don't rewrite from scratch.
+
+### 2. Run Explore sub-agents in parallel
+
+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*.
+- **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."
+
+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:
+
+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.
+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.
+8. **Footer** — one line: *"Generated by `/codebase-explainer`. Re-run to refresh."*
+
+No timestamps in the file body (dates rot). The git history is the timestamp.
+
+### 4. Render a condensed summary inline
+
+After writing the file, render in chat: the "Read this first" bullets verbatim, plus a one-sentence pointer to the file path. Do **not** re-paste the full document — the file is the artifact.
+
+### 5. Offer the share step (optional)
+
+If making this teammate-accessible would help, mention `ShareOnboardingGuide` — it uploads `ONBOARDING.md` and returns a link. Offer once; never auto-invoke.
+
+## Examples
+
+### Example 1: First pass on a six-month-old project
+
+**User:** "I haven't touched this repo since November — onboard me"
+
+**Claude:**
+1. Reads `package.json`, `next.config.ts`, `prisma/schema.prisma`, existing `README.md`. Notes: Next.js App Router + NextAuth + Prisma + Postgres.
+2. Spawns five Explore agents in parallel (overview, deps, startup, auth, important files) in one message.
+3. Synthesizes → writes `ONBOARDING.md` with startup flow rooted at `app/layout.tsx:12` → `lib/auth.ts:34` and auth flow citing the NextAuth `authOptions` and the `requireSession()` helper.
+4. Prints the "Read this first" bullets and the file path. Offers `ShareOnboardingGuide`.
+
+### Example 2: Refresh against an existing onboarding doc
+
+**User:** "/codebase-explainer — refresh the onboarding doc, I added Stripe and a new admin route last sprint"
+
+**Claude:**
+1. Reads existing `docs/ONBOARDING.md`. Spawns Explore agents scoped to "what's changed": new top-level deps, new routes under `app/**/route.ts`, auth changes.
+2. Updates the dependency map (Stripe row added with `lib/payments/stripe.ts:18` citation), appends the admin route to startup flow, leaves untouched sections alone.
+3. Reports a diff-style summary in chat: "+1 dep, +1 route, auth unchanged."
+
+## Anti-patterns
+
+- ❌ 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.
+- ❌ 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.
+- ❌ Rewriting an existing `ONBOARDING.md` from scratch when the user asked to refresh.
+- ✅ Tight "read this first," cited everywhere, explicit about absences, refreshable.
+
+## Notes
+
+- **Composes with** [`improve-codebase-architecture`](../improve-codebase-architecture/SKILL.md): an onboarding pass often surfaces shallow-module clusters worth a deepening review. Hand the user a pointer; don't propose refactors here.
+- **Composes with** [`handoff`](../handoff/SKILL.md): `ONBOARDING.md` is project-level orientation (durable across many sessions); a handoff is session-level state. Different artifacts, both useful.
+- **Composes with** [`grill-with-docs`](../grill-with-docs/SKILL.md): if exploration surfaces fuzzy domain terminology, a follow-up grilling pass to populate `CONTEXT.md` makes future onboarding sharper.
+- `ShareOnboardingGuide` (when available in the environment) uploads `ONBOARDING.md` and returns a teammate-shareable link. Optional; user-initiated.

package/skills/diagnose/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: diagnose
-description: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use this skill whenever the user says "diagnose this", "debug this", "/diagnose", reports a bug, says something is broken / throwing / failing / flaky / hanging / leaking, or describes a performance regression — even if they don't explicitly ask for a "diagnose skill".
+description: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. On non-trivial cases, Phase 3 spawns parallel `Explore` sub-agents — each defending a distinct hypothesis with falsifiable predictions and `file:line` evidence — then a cross-examination round drops the ones whose defender couldn't find support, breaking the single-chain anchoring trap. Trivial bugs skip the council. Use this skill whenever the user says "diagnose this", "debug this", "/diagnose", reports a bug, says something is broken / throwing / failing / flaky / hanging / leaking, or describes a performance regression — even if they don't explicitly ask for a "diagnose skill".
 ---
 
 # Diagnose
@@ -82,8 +82,31 @@ 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.
 
+### 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.
+- **Run the council** when there are multiple plausible causes, the bug spans modules, the regression appeared "somehow" between releases, or your first three hypotheses all feel equally plausible. Anchoring risk is highest exactly here.
+
+### Hypothesis council (parallel + adversarial)
+
+1. **Seed.** Jot 3–5 candidate hypotheses as one-liners. These are *seeds*, not analyses.
+2. **Spawn defenders in parallel.** Send a **single message** with N `Agent` calls (one per seed) using `subagent_type=Explore`. Each defender gets:
+   - The repro details and observed failure mode (verbatim).
+   - **One** hypothesis to defend.
+   - Instructions: "Build the strongest case for this hypothesis against the actual codebase. State the falsifiable prediction in the format above. Cite `file:line` for every piece of supporting evidence. If you cannot find supporting evidence in the code, say so explicitly — do not invent. Report in ≤300 words."
+3. **Cross-examine.** When all defenders return, read their cases side by side. For each hypothesis write:
+   - 2–3 falsifying checks the next phase will run (concrete, runnable).
+   - Whether the defender found real evidence or hand-waved.
+4. **Rank with the survivors.** Drop hypotheses whose defender couldn't find supporting evidence. Demote ones whose prediction is weak or untestable. Promote ones with clean `file:line` evidence + sharp predictions.
+
+The point isn't "vote by sub-agent." It's that forcing each angle to be developed *independently* against the real code prevents the chain-of-thought from anchoring on the first plausible idea.
+
+### Then: show the ranked list to the user
+
 **Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
 
+Include, per hypothesis: the falsifiable prediction, 1–2 lines of evidence with `file:line`, and the falsifying check Phase 4 will run.
+
 ## Phase 4 — Instrument
 
 Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
@@ -96,10 +119,14 @@ Tool preference:
 
 **Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
 
+**Library-API bugs — check current docs before guessing.** If the hypothesis points at a third-party library's behaviour (a framework method, an ORM call, an SDK), look up the library's *current* docs before instrumenting around assumed behaviour. Use `context7` (or any docs-MCP server available in the environment): `context7__resolve-library-id` → `context7__query-docs` for the specific symbol. Training-data API knowledge can be a version behind; the bug may be a known issue or already-fixed-upstream. Skip for refactoring own code, general programming concepts, or library behaviour you've already confirmed in this session.
+
 **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.
 
 ## Phase 5 — Fix + regression test
 
+**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.
 
 A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
@@ -130,6 +157,9 @@ 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.
+- 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.
 - "Added some logs" without tagging them — they survive into production.
 - Marking the bug fixed because the symptom went away once — without re-running the loop or adding a regression test, you don't know.
 - Treating a flaky test as flaky-by-nature and retrying — flakes are bugs with a low reproduction rate; raise the rate.

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

@@ -109,6 +109,7 @@ Use these exact patterns when generating files. Full templates are in `reference
 - **Centralized exception middleware** with env-aware response — see [`references/templates/exception-middleware.cs.md`](references/templates/exception-middleware.cs.md).
 - **Unified validation error response** via `InvalidModelStateResponseFactory`.
 - **JWT auth wiring** in a `RegisterAuth` extension method.
+- **Minimal comments in generated code.** Default to no comments. Only add one when the *why* is non-obvious — a workaround for a specific framework bug (with a link), a subtle invariant the code depends on, a domain rule that isn't visible from the names. Never write XML doc-comment blocks (`/// <summary>...`) on internal members; reserve them for genuinely public API surface that ships to consumers. Never restate *what* the next line does, never leave `// TODO` without an issue link. One short line max — no multi-line comment blocks. Well-named identifiers carry the *what*; comments earn their place only when they carry *why*.
 
 ### Eliminate (anti-patterns)
 

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

@@ -213,6 +213,7 @@ Full templates are in [`references/templates/`](references/templates/). Rational
 - **`error.tsx` and `loading.tsx` at every meaningful route segment**.
 - **Runtime env validation** in `src/config/env.ts` using Zod. `AUTH_SECRET`, `DATABASE_URL`, `AUTH_URL` (production), and any OAuth provider keys are required.
 - **Single date library: `date-fns`**. No `moment`.
+- **Minimal comments in generated code.** Default to no comments. Only add one when the *why* is non-obvious — a workaround for a specific upstream issue (with a link), a subtle invariant the code depends 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, no multi-paragraph JSDoc. Well-named identifiers carry the *what*; comments earn their place only when they carry *why*.
 - **`tsconfig.json` strict + `@/*` path alias** — see [`references/templates/tsconfig.md`](references/templates/tsconfig.md).
 - **Vitest + RTL for unit tests, Playwright for E2E**. At least: one reducer test, one schema test, one component test, one E2E auth-then-dashboard flow.
 - **Husky + lint-staged** pre-commit: `prettier --write` + `eslint --fix` on staged files.

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

@@ -1,6 +1,6 @@
 ---
 name: plan-and-build
-description: Plan-first feature builder. Grills the user about the feature until the design is unambiguous, presents a plan, gates on `ExitPlanMode` approval, then builds the feature using the project's existing patterns — TDD-first with NUnit when the work touches a .NET API (appending to the matching test class if one already exists), and writing migration files but never executing SQL or `dotnet ef database update`. Use this skill whenever the user says "build a feature", "add a feature", "implement this feature", "/plan-and-build", "plan and build", "new feature", or pastes a feature spec and asks you to design + implement it — even if they don't name the skill.
+description: Plan-first feature builder. Grills the user about the feature until the design is unambiguous, presents a plan, gates on `ExitPlanMode` approval, then builds the feature using the project's existing patterns — TDD-first with NUnit when the work touches a .NET API (appending to the matching test class if one already exists), and writing migration files but never executing SQL or `dotnet ef database update`. When Phase 3 hits a genuine design fork (e.g. service-layer vs. CQRS handler, sync vs. async, new table vs. nullable columns), runs **Design It Twice**: two parallel sub-agents each draft the strongest plan for one approach, then a debate round names the trade-offs and recommends one — the user sees a recommended plan with the rejected alternative noted so they can redirect. Skipped when an existing pattern in the repo already dictates the approach. Use this skill whenever the user says "build a feature", "add a feature", "implement this feature", "/plan-and-build", "plan and build", "new feature", or pastes a feature spec and asks you to design + implement it — even if they don't name the skill.
 ---
 
 # Plan and Build
@@ -66,9 +66,43 @@ Before designing, look at what the repo already does so the plan reuses it. Run
 
 Record what you find. The plan will reference these directly so the user can see you're not inventing new patterns.
 
+**Library API lookup — use `context7` when available.** If the plan needs an API from a third-party library or framework that's pinned in this repo (e.g. EF Core 8, Next.js 15, Prisma 5, NextAuth v5, Stripe SDK), check `context7` (or any docs-MCP server in the environment) for the *current* docs before drafting the plan: `context7__resolve-library-id` → `context7__query-docs` for the specific topic. Training-data API knowledge can be a major version behind, and a plan built on the wrong API shape wastes a Plan Mode round. Skip the lookup for libraries the user has already named in this session or for general programming concepts — only reach for it when the plan depends on a specific library symbol or pattern.
+
 ### Phase 3 — Plan
 
-Enter Plan Mode (`EnterPlanMode`). The plan must include:
+#### Decision gate: single plan vs. Design It Twice
+
+Before drafting, ask: **is there a genuine design fork here that the existing codebase doesn't already resolve?**
+
+- **Single plan** — when Phase 2 found a clear precedent (e.g. every other feature in this codebase uses CQRS handlers, or the project's slice template dictates the layout). Draft one plan and proceed.
+- **Design It Twice** — when there's a real choice with real trade-offs, and Phase 2 didn't settle it. Typical forks:
+  - Service-layer method vs. CQRS handler
+  - New table vs. nullable columns on an existing table
+  - Sync request/response vs. background job + status endpoint
+  - In-process event vs. message-queue publish
+  - REST endpoint vs. WebSocket / SSE
+  - Lifting state up vs. introducing a context/store
+  - One denormalised read model vs. join at query time
+
+Don't manufacture a fork to perform ceremony. If the answer is clear, the single plan is faster *and* better.
+
+#### Design It Twice (when convened)
+
+1. **Name the axis.** State the single design choice the two plans disagree on in one sentence (e.g. *"Add an `OrderAuditLog` table vs. extend `Orders` with `priority_set_by_user_id` + `priority_set_at`."*). If you can't name the axis cleanly, you don't have a genuine fork — drop to single plan.
+2. **Spawn two planners in parallel.** Send a **single message** with 2 `Agent` calls (general-purpose). Each gets:
+   - Phase 1 grilling outputs (verbatim, including the canonical terminology).
+   - Phase 2 stack and convention findings (verbatim).
+   - The named axis and **one** side of it to defend.
+   - Instructions: "Draft the BEST plan for your assigned approach. Include the seven items below ([Plan contents](#plan-contents)). Defend why this approach beats the alternative *on this codebase*. Where you must invent a new pattern (no Phase 2 precedent), justify it. Report in ≤700 words."
+3. **Debate round.** When both plans return, write inline:
+   - **3 things Plan A does better than Plan B.**
+   - **3 things Plan B does better than Plan A.**
+   - **The recommendation** (one paragraph) — which plan, and why it wins on this codebase. Cite the Phase 1 / Phase 2 evidence that broke the tie.
+4. **Pick the recommended plan** as the one to present. Carry forward only the winning plan's contents — but keep a one-line note of the rejected alternative for the user.
+
+#### Plan contents
+
+Whether you drafted one plan or chose between two, the presented plan must include:
 
 1. **Restatement of the feature** in one short paragraph, using the project's canonical terminology from `CONTEXT.md` (if present).
 2. **Files to create**, grouped by layer, each with a one-line purpose.
@@ -82,7 +116,11 @@ Enter Plan Mode (`EnterPlanMode`). The plan must include:
 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.
 
-Then exit with `ExitPlanMode` and wait. **Do not write a single file until the user approves the plan.** If the user pushes back, revise and re-present; don't half-implement against an unapproved plan.
+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.
+
+#### Enter and exit plan mode
+
+Enter Plan Mode (`EnterPlanMode`) to present. Then exit with `ExitPlanMode` and wait. **Do not write a single file until the user approves the plan.** If the user pushes back — including "actually let's go with the alternative" — revise and re-present; don't half-implement against an unapproved plan.
 
 ### Phase 4 — Build (test-first when an API changes)
 
@@ -173,6 +211,10 @@ When appending:
 - ❌ 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.
+- ❌ Running Design It Twice when the codebase already dictates the approach. Ceremony, not value.
+- ❌ Manufacturing a fake axis to perform a debate. If you can't name the axis in one sentence, you don't have a fork.
+- ❌ Spawning the two planners serially instead of in parallel — one message, two agents.
+- ❌ Presenting both plans to the user. The user sees the recommended plan plus a one-line "considered alternative" note — not two full plans to grade.
 - ❌ Running `dotnet ef database update`, `prisma migrate deploy`, or any DDL against the user's DB.
 - ❌ Running ad-hoc `SELECT` / `UPDATE` queries against the user's DB to "check something" — ask the user instead.
 - ❌ Block comments and "what this does" comments. Names should do that work.

package/skills/pr-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pr-review
-description: Conduct a thorough, structured code review of a local branch, grouped by task number (#NNN) referenced in commit messages. Use this skill whenever the user asks to review a PR, asks for feedback on a diff or branch, mentions "review my changes", or pastes code asking what could be improved. Auto-detects all tasks on the branch and produces one verdict per task. Covers correctness, design, tests, security, performance, and readability in that priority order.
+description: Conduct a thorough, structured code review of a local branch, grouped by task number (#NNN) referenced in commit messages. On non-trivial tasks, convenes a **per-task lens council** — parallel `Explore` sub-agents reviewing through distinct lenses (correctness / design / security / tests) — then an adversarial critique round that challenges each lens's blocking flags against context from the others, demoting false positives and surfacing contradictions for the user. Small tasks skip the council. Use this skill whenever the user asks to review a PR, asks for feedback on a diff or branch, mentions "review my changes", or pastes code asking what could be improved. Auto-detects all tasks on the branch and produces one verdict per task. Covers correctness, design, tests, security, performance, and readability in that priority order.
 ---
 
 # Pull Request Review
@@ -36,8 +36,10 @@ Review in this order — earlier categories matter more, and finding issues ther
 4. **For each task, read its intent first.** What is `#123` trying to accomplish? Infer from the commit subjects/bodies in that bucket. If intent is unclear, ask the user before reviewing — "is the code correct" is unanswerable without it.
 5. **Get the per-task diff.** For each task, view its commits with `git show <sha>` per commit, or `git diff <first>^..<last>` if the commits are contiguous. Don't merge tasks into one combined diff — keep them scoped.
 6. **Skim each task once, top to bottom.** Get a mental model of what changed before commenting on specifics.
-7. **Re-read each task with the priority list in mind.** Note issues as you go.
-8. **Look at the tests in each task.** Do they test the new behavior or just exercise the new lines?
+7. **Per-task decision: single-pass vs. lens council** (see [Lens council](#lens-council-for-non-trivial-tasks)):
+   - **Single-pass (inline)** when the task is small and tightly scoped — roughly: < 100 lines of task-scoped diff, < 5 files, no security-sensitive paths. Walk the priority list yourself.
+   - **Lens council** otherwise. Spawn parallel `Explore` sub-agents per lens, then run a critique round before the per-task verdict.
+8. **Look at the tests in each task.** Do they test the new behavior or just exercise the new lines? (The lens council's Tests agent handles this when convened.)
 9. **Check what's *not* in each task's diff.** Missing error handling, missing tests for edge cases, missing migration for a schema change.
 
 ## How to phrase feedback
@@ -85,6 +87,46 @@ Lead with the *why*, not just the *what*. "This will deadlock if two callers hit
 - Synchronous I/O in hot paths
 - Repeated work that could be hoisted out of a loop
 
+## Lens council (for non-trivial tasks)
+
+A single chain of reasoning across all priority categories anchors on whatever was seen first. For non-trivial tasks, run the lenses **in parallel** per task, then critique before the verdict.
+
+### When to convene the council (per task)
+
+- The task's diff is ≥ ~100 lines, **or** touches ≥ 5 files, **or** edits security-sensitive paths (auth, crypto, input validation, SQL/shell/HTML sinks, file paths from user input).
+- Or first-skim turned up contradictions you can't resolve from memory.
+
+Otherwise stay single-pass for that task. Some branches have one trivial task and one huge one — convene only for the huge one.
+
+### Lenses
+
+Spawn one sub-agent per lens for the task being reviewed. Default set:
+
+| Lens | Looks for |
+|---|---|
+| **Correctness** | Off-by-one, null/undefined at boundaries, concurrent-access bugs, swallowed exceptions, default-value behaviour shifts |
+| **Design** | New abstractions that don't earn their keep, tight coupling, duplication that should unify, public-API breakage, state in the wrong place |
+| **Security** | Untrusted input into sinks, secrets in code/logs/errors, missing authn/authz on new endpoints, weak/hand-rolled crypto |
+| **Tests** | Assertion-free / over-mocked tests, missing edge cases, flaky-by-design tests, new behaviour in the diff with **no** new test |
+
+Performance + Readability usually fold into Design — only spawn a dedicated lens for them if the task is genuinely perf-sensitive or the project has no linter.
+
+### How to run it (per task)
+
+1. **Spawn in parallel.** Send a **single message** with N `Agent` calls (`subagent_type=Explore`), one per lens. Each gets:
+   - 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."
+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).
+   - **Merge near-duplicates** across lenses.
+   - **Promote** any finding multiple lenses raised independently — that's a real signal.
+3. **Verdict.** With the surviving findings, decide: Approve / Approve with suggestions / Request changes / Comment.
+
+Each task gets its own council pass. Tasks remain independent — the council scope **never** crosses task boundaries.
+
 ## Output format
 
 Produce one section per task, with comments grouped by file and line inside each. Each task gets its own verdict — tasks are independent units of work and should be approvable or blockable on their own.
@@ -130,3 +172,8 @@ End with a one-line roll-up: e.g. `Overall: 2 approve, 1 request changes, 1 unsc
 - ❌ "I would have done it differently" without a concrete reason
 - ❌ 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.
+- ❌ Spawning lens agents serially instead of in parallel — one message, N agents, per task.
+- ❌ Letting the council span tasks. Each `#NNN` is its own review — sub-agents see only that task's diff.
+- ❌ Publishing the raw union of lens findings without the critique round. False-positive blockers erode trust.
+- ❌ Dumping per-agent transcripts into the user's report. The council is internal deliberation — the user sees the synthesized per-task verdict.

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

@@ -191,6 +191,7 @@ Full templates are in [`references/templates/`](references/templates/). The full
 - **`tauri.conf.json` `windows[].devtools: false`** (or omitted — Tauri defaults to off in release). DevTools should be opened from a build-time feature flag, not the production config.
 - **Reset-state-on-startup pattern** — in `pub fn run()`'s `.setup(|app| { ... })`, clear any in-progress / stuck state from a previous run before showing the window. Crashes leave globals in odd places; treat each startup as recovering from "the app was force-quit".
 - **Show window FIRST in `.setup()`** before any blocking initialization. Heavy work (ML model loading, large config parses) goes on a background thread that emits events back to the frontend.
+- **Minimal comments in generated code (Rust and TS).** Default to no comments. Only add one when the *why* is non-obvious — `// SAFETY:` on an `unsafe` block, a workaround for a specific upstream bug (with a link), a non-trivial invariant the code depends on, a platform quirk that isn't visible from the names. Never write Rust doc-comment blocks (`///`) on internal items; reserve them for genuinely public API surface (`pub` types crossing crate boundaries). Never restate *what* the next line does, never leave `// TODO` without an issue link. One short line max — no multi-line comment blocks. `// SAFETY:` on `unsafe` is the one place verbose justification is *required*; everywhere else, well-named identifiers carry the *what* and comments earn their place only when they carry *why*.
 
 ### Eliminate (anti-patterns)