@dennisrongo/skills 0.5.0 → 0.6.0

package/README.md

@@ -104,6 +104,7 @@ node bin/claude-skills.js list
 | [`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`. |
 | [`ship-it`](./skills/ship-it/SKILL.md) | Pre-launch **operational-readiness** gate for a feature, release, or branch — the complement to [`code-review`](./skills/code-review/SKILL.md). Walks a fixed 10-category checklist (logging, error handling, telemetry, feature flags, migrations, rollback strategy, secrets, local-first storage, auth, update strategy) against the named scope and produces a structured report with PASS / GAP / N/A per item — every PASS backed by a `file:line` citation, every GAP labelled `no evidence found at <path>`, every N/A justified in one line. The final verdict groups findings as **Blocking** (secrets in code, missing authz on a new endpoint, destructive migration without rollback, no way to disable the change in prod) / **Should-fix** / **N/A with reason** / **Passing**, then asks per-blocker whether to draft a fix. **Never edits code unprompted** and **forces scope before auditing** — a PR, a flag, a release tag, or a module — so the output stays actionable. Distinct from `code-review` (diff quality) and `pr-review` (branch / per-task review): `ship-it` is the operational gate that catches what diff-level reviews don't surface. Triggers on "is this ready to ship?", "ship-it check", "production checklist", "pre-launch checklist", "release readiness", or `/ship-it`. |
+| [`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). |
 | [`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". |

package/package.json

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

@@ -0,0 +1,233 @@
+---
+name: sql-review
+description: Pre-commit SQL code review for uncommitted database changes. Detects antipatterns that cause real production incidents — `sp_send_dbmail` in CATCH blocks (masks the real error 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 (silent perf-then-deadlock killer), parameter-vs-column type mismatches (8152 truncation risk), `EXEC()` string concatenation without `sp_executesql` parameters (SQL injection), `NOLOCK` in write paths, `UPDATE`/`DELETE` without `WHERE`, cursors without `READ_ONLY FORWARD_ONLY LOCAL`, hardcoded env values (emails, server names, paths), cross-DB references like `msdb.dbo.*`, missing `SET NOCOUNT ON`, missing `GRANT EXECUTE` on `CREATE PROC`, `BEGIN TRANSACTION` outside `TRY`/`CATCH`, and vestigial control-flow comments hinting at refactor leftovers (e.g. `-- end while loop` with no `WHILE`). Reports findings as `BLOCKER` / `WARN` / `INFO` with `file:line` citations and per-finding fix recommendations. **Never edits SQL** — surfaces findings for human review. Use this skill whenever the user says "/sql-review", "review my SQL", "review the SQL diff", "lint the SQL", "check my SQL changes", "SQL pre-commit check", "audit my stored proc", or "any SQL antipatterns in this diff" — even if they don't explicitly say "SQL review skill". Distinct from `code-review` (general best-practice review) — this carries SQL-specific patterns that surface DB-layer production incidents.
+---
+
+# SQL Review
+
+Review uncommitted SQL changes against a catalog of patterns that cause real production incidents — masked errors, unindexed new tables, silent truncation, SQL injection, deadlock-prone CATCH blocks — and surface findings as recommendations the user can act on, **without editing SQL unprompted**.
+
+## When to use this skill
+
+- "/sql-review" / "review my SQL" / "review the SQL diff"
+- "lint the SQL" / "SQL pre-commit check" / "check my SQL changes"
+- "audit my stored proc" / "any SQL antipatterns in this diff"
+- Before committing a `.sql` change touching a stored procedure, function, or table
+
+Do **not** auto-trigger when the user is asking for a *general* code review on a mixed diff — defer to [`code-review`](../code-review/SKILL.md) for that. This skill is specifically for SQL-heavy diffs where the antipattern catalog applies.
+
+## Hard rule: surface, don't refactor
+
+If you find issues, **do not start editing the SQL**. Produce the findings report first. After delivering it, ask the user per finding: *"Want me to fix #N?"* — and wait for an explicit yes. Pre-authorization ("fix them all") proceeds through the list; absent that, default to ask-per-fix.
+
+SQL changes are particularly sensitive because they often run against production data in a single non-reversible deployment. A drive-by refactor mid-review is more dangerous here than in application code.
+
+## Workflow
+
+1. **Snapshot the SQL diff.** Run in parallel:
+   - `git status --short` — see what's modified, staged, untracked.
+   - `git diff -- '*.sql'` — unstaged SQL changes.
+   - `git diff --staged -- '*.sql'` — staged SQL changes.
+   - If user passed an explicit range (e.g. `main..HEAD`), use that instead: `git diff <range> -- '*.sql'`.
+2. **Triage files into two buckets:**
+   - **New files** (status `A` or `??`) — review the entire file. The whole file is new code; pre-existing antipatterns elsewhere don't apply.
+   - **Modified files** (status `M`) — review only the changed hunks. The rest of the file may have legacy antipatterns the user isn't introducing (e.g. existing repos commonly have dozens of SPs with the `sp_send_dbmail`-in-CATCH pattern; flagging all of them on an unrelated edit creates noise).
+3. **For each check in [What to check](#what-to-check), look for the pattern** in the relevant scope (whole file for new files, diff hunks for modified files). Use ripgrep — don't try to fully parse SQL.
+4. **Categorize each finding** as `BLOCKER` / `WARN` / `INFO` (see [Categories](#categories)).
+5. **Cite `file:line`** for every finding. Line numbers come from the diff or the current file content.
+6. **Produce the report** in the [Output format](#output-format).
+7. **Offer to fix** the suggested findings. Wait for the user's selection before editing.
+
+## Categories
+
+- **`BLOCKER`** — would cause a production incident: silent data loss, masked errors, SQL injection, unindexed table that will grow, broken transaction handling. Fix before commit.
+- **`WARN`** — likely a bug or maintenance hazard: NOLOCK in write paths, hardcoded environment values, missing `SET NOCOUNT ON`, cross-DB references. Should fix but won't necessarily incident.
+- **`INFO`** — style / convention / hygiene: vestigial comments, cursor defaults, missing `GRANT EXECUTE` where the project's pattern exists.
+
+Lead each finding with the *why*. "This swallows the original error and surfaces a misleading permission denial" beats "add `;THROW;`".
+
+## What to check
+
+Use ripgrep for detection. The patterns below are starting points — adapt to the actual diff text.
+
+### Error-handling antipatterns (BLOCKER class)
+
+1. **`sp_send_dbmail` inside `CATCH`** — masks the real exception with a permission/configuration error when the executing login lacks `EXECUTE` on `msdb.dbo.sp_send_dbmail`. The real underlying error is silently lost.
+   - Pattern: `rg -n -B 20 'sp_send_dbmail' <file>` → check whether the surrounding context is a `BEGIN CATCH`.
+   - **Fix:** Replace with `;THROW;` to re-raise, or write the error info to a local log table. Never `sp_send_dbmail` from inside operational SPs.
+
+2. **Broken retry pattern** — `DECLARE @retry INT = N;` exists, but no `WHILE @retry` loop wraps the `TRY`/`CATCH`. The retry variable is decremented in the CATCH but never read, so the SP gives up on the first deadlock instead of retrying.
+   - Pattern: `rg -n '@retry' <file>` → confirm there's a matching `WHILE.*@retry` somewhere in the same SP body.
+   - **Fix:** Add the missing `WHILE @retry > 0 BEGIN ... END` around the TRY/CATCH, or remove the vestigial variable entirely.
+
+3. **Empty / swallowing `CATCH` blocks** — `BEGIN CATCH ... END CATCH` with no `THROW`, no `RAISERROR`, and no `INSERT INTO <error_log_table>`. Silent failure → silent data loss.
+   - Pattern: `rg -n -A 30 'BEGIN CATCH' <file>` → check each match for at least one of `THROW`, `RAISERROR`, or `INSERT INTO`.
+   - **Fix:** End the CATCH with `;THROW;` unless there's a deliberate reason to suppress (and document that reason).
+
+4. **`BEGIN TRANSACTION` without `TRY`/`CATCH` + `XACT_STATE` handling** — an error mid-transaction leaves an open transaction on the connection.
+   - Pattern: `rg -n 'BEGIN TRAN' <file>` → confirm the same SP has `BEGIN TRY` and `XACT_STATE()` checks in CATCH.
+   - **Fix:** Wrap in `BEGIN TRY / BEGIN TRANSACTION ... COMMIT TRANSACTION / END TRY / BEGIN CATCH / IF XACT_STATE() = -1 ROLLBACK; IF XACT_STATE() = 1 COMMIT; ;THROW; / END CATCH`.
+
+5. **Vestigial control-flow comments** — `-- end while loop` with no `WHILE` keyword, `-- retry on deadlock` with no retry loop, etc. Strong signal that a refactor left dead code behind.
+   - Pattern: `rg -n -- '-- end (while|for|repeat)' <file>` → check for matching opening keyword.
+   - **Fix:** Either restore the missing loop or delete the misleading comment.
+
+### Schema / performance antipatterns (BLOCKER for new tables, WARN otherwise)
+
+6. **New `CREATE TABLE` without a primary key, clustered index, or any index** — heap tables will deadlock-and-table-scan once they grow. This is the exact pattern that caused real production deadlocks.
+   - Pattern: `rg -n -A 50 'CREATE TABLE' <file>` → confirm at least one of `PRIMARY KEY`, `CLUSTERED INDEX`, or `CREATE INDEX` exists on that table within the diff or in a sibling file.
+   - **Fix:** Add `PRIMARY KEY CLUSTERED` on the natural ID column. If the table is append-mostly with no natural ID, add a clustered index on the column the populating SPs filter by in `WHERE`.
+
+7. **Parameter-to-column type-width mismatches** — passing `@x VARCHAR(50)` into a column declared `VARCHAR(3)` causes silent truncation (or runtime error 8152 depending on `ANSI_WARNINGS`).
+   - Pattern: cross-reference the SP's `@param VARCHAR(N)` declarations against the target table's column widths. Flag any narrowing.
+   - **Fix:** Match widths between parameter and column, or add explicit `LEFT(@x, 3)` truncation at the boundary so it's intentional and visible.
+
+8. **Implicit type conversions in `JOIN` / `WHERE`** — `WHERE intCol = @varcharParam` defeats indexes and produces table scans.
+   - Pattern: `rg -n -i 'WHERE\s+\w+\s*=\s*@\w+' <file>` → cross-check parameter type vs. column type.
+   - **Fix:** Match the parameter type to the column type. If they're authoritatively different, cast the *parameter*, not the column (casting the column kills the index).
+
+### Security antipatterns (BLOCKER)
+
+9. **Dynamic SQL via string concatenation passed to `EXEC()`** without `sp_executesql @stmt, @params` parameterization — SQL injection.
+   - Pattern: `rg -n 'EXEC\s*\(' <file>` → confirm any string-concat dynamic SQL nearby uses `sp_executesql` with parameters, not `EXEC(@strSQL)` with values inlined.
+   - **Fix:** Switch to `EXEC sp_executesql @stmt = @strSQL, @params = N'@p1 INT, @p2 VARCHAR(50)', @p1 = @value1, @p2 = @value2;`.
+
+10. **Hardcoded environment-specific values** — email addresses, server names, file paths, IP addresses, connection strings.
+    - Pattern: `rg -nE "'[\w.-]+@[\w.-]+\.\w+'|@server_name\s*=\s*'\w+'|\\\\\\\\[\\w.-]+\\\\" <file>` (emails, linked servers, UNC paths).
+    - **Fix:** Move env-specific values into a configuration table or pass them as parameters from the application layer.
+
+11. **Cross-database references** — `msdb.dbo.*`, `master.dbo.*`, linked server `[srv].db.dbo.*`. These require permissions that may not exist in all environments (the canonical example: a SP calling `msdb.dbo.sp_send_dbmail` from a login that lacks EXECUTE on it).
+    - Pattern: `rg -n 'msdb\.|master\.dbo\.|\[\w+\]\.\w+\.\w+\.' <file>`.
+    - **Fix:** Move the cross-DB call out of operational SPs into infrastructure-owned code. If it must stay, document the required permission in a comment so deployments to new environments include the GRANT.
+
+### Correctness / data-safety antipatterns (BLOCKER)
+
+12. **`UPDATE` or `DELETE` without a `WHERE` clause** — almost always a bug; will affect every row.
+    - Pattern: `rg -n -B 0 -A 20 'UPDATE\s+\w+' <file>` → confirm a `WHERE` clause is present and not commented out.
+    - Pattern: `rg -n -B 0 -A 10 'DELETE\s+FROM' <file>` → same.
+    - **Fix:** Add the `WHERE` clause. If "every row" really is intended (TRUNCATE-style), use `TRUNCATE TABLE` and add a comment explaining why.
+
+13. **`NOLOCK` / `READ UNCOMMITTED` inside transactional write paths** — `WITH (NOLOCK)` is fine for ad-hoc reporting reads, but in an `UPDATE`/`INSERT`/`DELETE` SP it can read uncommitted data and corrupt the write.
+    - Pattern: `rg -n -i 'NOLOCK|READ UNCOMMITTED' <file>` → check whether the same SP has `INSERT`, `UPDATE`, or `DELETE` against the same tables.
+    - **Fix:** Remove the hint on tables being modified. Consider `SNAPSHOT` isolation if the goal is to avoid blocking.
+
+14. **`TRUNCATE TABLE` or `DROP` without `IF EXISTS`** in deploy scripts that are supposed to be idempotent (re-runnable). Many repos use flat idempotent `Deploy_*.sql` files where re-runs must not fail on missing objects.
+    - Pattern: `rg -n -i 'DROP (TABLE|PROC|FUNCTION|VIEW)' <file>` → confirm `IF EXISTS` or `OBJECT_ID(...) IS NOT NULL` guard.
+    - **Fix:** `IF OBJECT_ID('dbo.X', 'U') IS NOT NULL DROP TABLE dbo.X;` or `DROP TABLE IF EXISTS dbo.X;` (SQL 2016+).
+
+### Style / convention (WARN/INFO)
+
+15. **Missing `SET NOCOUNT ON`** at the top of a new `CREATE PROC` — causes extra round-trips to the client and breaks some ORM drivers that don't handle row-count messages.
+    - Pattern: `rg -n -A 5 'CREATE PROC' <file>` → confirm `SET NOCOUNT ON` appears within the first ~10 lines of the procedure body.
+    - **Fix:** Add `SET NOCOUNT ON;` as the first statement after `AS BEGIN`.
+
+16. **Cursors without `READ_ONLY FORWARD_ONLY LOCAL`** — default cursors are slow and persist beyond the current batch.
+    - Pattern: `rg -n 'DECLARE\s+\w+\s+CURSOR\b' <file>` → confirm `READ_ONLY FORWARD_ONLY LOCAL` (or `FAST_FORWARD`) is specified.
+    - **Fix:** `DECLARE c CURSOR READ_ONLY FORWARD_ONLY LOCAL FOR SELECT ...`.
+
+17. **Missing `GRANT EXECUTE` at end of `CREATE PROC`** — only flag when the rest of the repo has a consistent `GRANT EXECUTE ON ... TO <role>` pattern at the end of every SP file. Detect the pattern by sampling a few neighboring `.sql` files; if every existing SP grants to the same role and this new SP doesn't, flag it.
+    - Pattern: `rg -n 'GRANT\s+EXECUTE' <file>` → confirm present if the repo convention requires it.
+    - **Fix:** Append `GRANT EXECUTE ON [dbo].[<proc>] TO [<app_role>] GO` matching the role the rest of the repo grants to.
+
+## Output format
+
+```
+# SQL review — uncommitted changes
+
+**SQL files changed:** <N> (<S new>, <M modified>)
+
+---
+
+## Verdict
+**Ship / Fix blockers first**
+
+<one-paragraph summary of the change and overall state>
+
+---
+
+## Blockers (<N>)
+
+### B1. <short title> — `path/to/file.sql:<line>`
+**Why:** <root cause / production consequence — one line>
+**Fix:** <concrete recommendation — one line>
+
+### B2. ...
+
+## Warnings (<N>)
+
+### W1. <short title> — `path/to/file.sql:<line>`
+**Why:** ...
+**Fix:** ...
+
+## Info (<N>)
+- `path:line` — <one-liner>
+
+---
+
+## Summary
+- BLOCKER: <count>
+- WARN: <count>
+- INFO: <count>
+
+## Fixes I can apply
+
+If you want, I can apply any of: B1, B2, W1. Which? (or "all", or "none")
+```
+
+End with the offer. Wait for the user's choice.
+
+## Examples
+
+### Example 1: New stored proc with mixed issues
+
+**User:** "/sql-review"
+
+**Claude:**
+- Runs `git diff --staged -- '*.sql'` and `git diff -- '*.sql'` in parallel.
+- Finds one new file `Stored Procedures/dbo.usp_NewSave.sql`.
+- Spots:
+  - `B1` — `BEGIN CATCH` without `;THROW;` (line 88) — swallowing.
+  - `B2` — calls `EXEC msdb.dbo.sp_send_dbmail` inside that CATCH (line 92) — masking risk.
+  - `W1` — missing `SET NOCOUNT ON` at line 6.
+  - `W2` — `WITH (NOLOCK)` on the table being UPDATEd (line 45).
+  - `I1` — missing `GRANT EXECUTE` at end of file (the repo's other SPs all end with it).
+- Reports, then asks: "Want me to fix B1, B2, W1, W2, I1?"
+
+### Example 2: Adding a new table — the canonical incident pattern
+
+**User:** "review the SQL diff before I push"
+
+**Claude:**
+- Spots `Tables/dbo.NewAuditLog.sql` (new file) — `CREATE TABLE` declared but **no PRIMARY KEY, no CLUSTERED INDEX, no CREATE INDEX**.
+- Flags as `B1` — "Heap table will table-scan on every read/UPDATE. Once the table grows past a few hundred thousand rows under concurrent writes, SQL Server's optimizer picks parallel plans and the workers deadlock on heap pages — a recurring production incident pattern."
+- Fix: "Add `PRIMARY KEY CLUSTERED (id)` or a clustered index on the lookup column."
+- Also flags the SP that populates the new table (`B2` — implicit type conversion `WHERE recordID = @recordID` where the new table's `recordID` is `INT` but the param is declared `VARCHAR`).
+
+### Example 3: Modified existing SP — flag only new badness, not legacy
+
+**User:** "lint the SQL — just the staged hunks"
+
+**Claude:**
+- The file `usp_UpdateBigOldSP.sql` is modified but huge. The user's diff added a 20-line block that does `UPDATE dbo.Customers SET ...` without a `WHERE` clause.
+- **Only flags the new block's `UPDATE` without `WHERE` as `B1`** — does NOT flag the legacy `sp_send_dbmail` call elsewhere in the file (which was already there before the user's edit).
+- Notes in the report footer: "1 pre-existing antipattern observed in this file but outside the diff — flagging suppressed per scope. Full-file audit available on request."
+
+## Anti-patterns
+
+- ❌ Trying to parse SQL with a full grammar — use ripgrep on the diff text. The skill is heuristic by design.
+- ❌ Flagging every existing antipattern in a modified file. Stay scoped to the diff for modified files; full-file scan only for new files.
+- ❌ Editing SQL during the review pass. Report first, **always**.
+- ❌ 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`.
+- ❌ 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.
+
+## Notes
+
+- The check catalog is intentionally finite — 17 checks chosen because each one maps to a real production incident class. Don't try to be a full SQL linter (e.g. SQLFluff or sqlcheck) — those exist and run from CI; this skill is the pre-commit human-pass complement focused on bug classes that linters miss.
+- For repos that use flat idempotent `Deploy_*.sql` files (every deploy is a full re-run), check #14 (`DROP` / `TRUNCATE` without `IF EXISTS`) is critical — the deploy will fail on second run otherwise. For repos that use forward-only migrations, this check is lower priority.
+- The "broken retry" pattern (check #2) is sneakier than it sounds: a `DECLARE @retry INT = 5;` followed by `SET @retry = @retry - 1;` in CATCH but no `WHILE` loop *looks* like deadlock handling. It isn't. Multiple SPs in real codebases have this bug from removed-loop refactors.
+- If the user wants the broader cleanup (refactor every legacy SP in the repo with one of these issues), recommend opening a tracked task rather than doing it in the current review — these fixes ripple through deploy pipelines and need coordinated review.
+- This skill composes downstream with [`code-review`](../code-review/SKILL.md) — on a mixed diff (`.cs` + `.sql`), run `code-review` for the application code and `sql-review` for the database changes.