@dennisrongo/skills 0.4.0 → 0.6.0

package/README.md

@@ -104,6 +104,8 @@ 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.4.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.

package/skills/task-executor/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: task-executor
+description: Disciplined execution loop for a single defined task — Understand → Inspect → Plan → Execute incrementally → Validate after every change → Track assumptions → Update progress. Forces a strict per-turn output format (Goal / Current understanding / Files to inspect / Plan / Progress / Risks / Assumptions) so the work stays legible and resumable instead of devolving into ad-hoc edits. When the inspection set spans multiple layers (controller + service + persistence + tests), Phase 2 convenes an **inspection council**: parallel `Explore` sub-agents — one per layer — each map their slice 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 execution. Small inspection sets skip the council. Enters Plan Mode after inspection and gates on `ExitPlanMode` approval before writing any code. Each incremental change is followed by a validation step (run the test, build, type-check, or curl the endpoint) before moving to the next checkbox. Use this skill whenever the user says "/task-executor", "Work on task: <description>", "task-executor", or hands you a single concrete task to execute with discipline — even if they don't name the skill. Do **not** auto-trigger on greenfield feature design with a fuzzy spec — use [`plan-and-build`](../plan-and-build/SKILL.md) instead, which interviews the user to design the feature before this skill's executional discipline applies.
+---
+
+# Task Executor
+
+A discipline for working on a single, already-defined task. The task is given; the goal is to execute it without skipping context, without batching changes, and without losing the thread mid-way. Every turn emits the same six sections so the user (and any future session) can pick up the state at a glance.
+
+## When to use this skill
+
+- The user runs `/task-executor` or types "task-executor".
+- The user says "Work on task: …" with a concrete task description (a ticket, a bullet, a paragraph spec).
+- The user hands you a defined deliverable and asks you to execute it — not to design it from scratch.
+
+Do **not** use this skill for:
+
+- Fuzzy or greenfield feature work where the spec still needs grilling. Use [`plan-and-build`](../plan-and-build/SKILL.md) for that — it includes the interview phase this skill skips.
+- Bug diagnosis. Use [`diagnose`](../diagnose/SKILL.md).
+- One-line fixes, renames, doc edits — the per-turn output format is more ceremony than value at that size.
+
+If the user invokes this skill on a spec that turns out fuzzy mid-flight, stop and recommend `plan-and-build` rather than pretending the spec is clear.
+
+## The per-turn output format (non-negotiable)
+
+Every assistant turn during this skill — from the first response to the final report — opens with these six sections, in this order, with exactly these headers. Sections that have nothing yet say `_(none yet)_` rather than being omitted, so the structure stays scannable.
+
+```markdown
+## Goal
+<one short paragraph — the task in the user's terms, restated>
+
+## Current understanding
+<what is now known about the task, the code, the constraints — updated each turn>
+
+## Files to inspect
+- path/to/file1.ext — why
+- path/to/file2.ext — why
+
+## Plan
+1. Step
+2. Step
+3. Step
+
+## Progress
+- [x] Completed step (with one-line evidence: test passing, command output, file written)
+- [ ] Pending step
+- [ ] Pending step
+
+## Risks
+- Risk or open question
+- Risk or open question
+
+## Assumptions
+- Assumption being relied on that has NOT been confirmed by code or the user
+- Assumption being relied on that has NOT been confirmed by code or the user
+```
+
+Rules:
+
+- **Restate the goal verbatim each turn.** It anchors against drift. If the user redirects, update the goal and note the redirect in `Current understanding`.
+- **Files to inspect is a live list.** Add as you discover relevance; mark a file as inspected by moving it into `Current understanding` with what you learned. Don't carry a file in both places.
+- **Progress checkboxes are append-only across turns.** Never silently delete a step — if a step is dropped, leave it ticked or struck and explain in `Current understanding`.
+- **Assumptions get promoted or killed.** When you confirm an assumption (by reading the code, running the loop, or asking the user), move it into `Current understanding` as a fact and remove it from `Assumptions`. When you falsify one, say what changed.
+
+If the conversation runs long and the sections grow, **compact** rather than truncate: collapse old completed steps into a one-line summary at the top of `Progress` and keep the active checkboxes verbatim.
+
+## Phases
+
+### Phase 1 — Understand
+
+Restate the task back to the user in your own words inside the `Goal` section of the first turn. Surface anything ambiguous as a `Risks` item or, if it blocks design, ask **one** clarifying question with `AskUserQuestion`. Do not interview broadly — this skill assumes the spec is given. If you find yourself with more than two clarifying questions, stop and recommend `plan-and-build`.
+
+Specifically capture in `Current understanding`:
+
+- What done looks like (the user's acceptance criteria, or your inferred version if they didn't state one).
+- Constraints that are stated, not inferred (auth model, framework, persistence, naming).
+- Anything the user said NOT to do.
+
+Anything you're filling in by inference goes into `Assumptions`, not `Current understanding` — until it's confirmed.
+
+### Phase 2 — Inspect
+
+Before drafting a plan, read the relevant code. Populate `Files to inspect` as a working set, then actually read them — don't list-and-skip. Use `Glob` / `Grep` / `Read` in parallel where the lookups are independent. Stop reading when you understand:
+
+- The existing pattern for whatever layer this task touches (controller, page, service, hook, migration).
+- The wiring points the new code needs to hook into (DI registration, route table, exports, schema).
+- Any sibling test class or test file the new tests should be appended to.
+
+Move each inspected file from `Files to inspect` into `Current understanding` with a one-line takeaway. Skip generic file summaries — note only the takeaway that affects the plan.
+
+#### Decision gate: inline reads vs. inspection council
+
+Be honest about scope before deciding. Manufacturing a sub-agent council for a three-file task is ceremony.
+
+- **Inline reads (default)** when the inspection set is ≤ ~5 files or stays inside one layer / module. Read them directly with `Read` (in parallel) and roll the takeaways into `Current understanding`.
+- **Inspection council** when the set spans ≥ 2 distinct layers (e.g. controller + service + persistence + tests) and the total reading is wide enough that doing it inline would burn the main context — especially since every turn of this skill re-emits the six-section output block. The council protects the working window so you can still execute cleanly over many turns.
+
+#### Inspection council (parallel `Explore` sub-agents)
+
+When convened:
+
+1. **Slice by layer / area.** Name 2–4 distinct slices of the codebase the plan will touch (e.g. *Controller + routing*, *Service / domain*, *Persistence + migrations*, *Tests + fixtures*). Each slice gets one sub-agent. Slices must be non-overlapping — if two slices would re-read the same files, merge them.
+2. **Spawn in parallel.** Send a **single message** with N `Agent` calls using `subagent_type=Explore`, one per slice. Each agent gets a self-contained brief:
+   - The verbatim task (the `Goal` paragraph).
+   - The one slice it owns and what to map within it.
+   - What to report: existing pattern for that layer, wiring points the new code must hook into, sibling test class / test file to append to, any forbidden-pattern signals (e.g. "no `ExecuteSqlRaw`", "no direct `fetch` in server components"), and `file:line` citations for every claim.
+   - Hard constraint: "Do not propose a plan. Do not invent. If you cannot find an existing pattern in your slice, say so explicitly — do not fabricate."
+   - Length cap: ≤ 300 words.
+3. **Aggregate, don't duplicate.** When all sub-agents return, merge their findings into `Current understanding` as one consolidated picture — not four parallel sections. Each finding keeps its `file:line` citation. Anything no sub-agent could find a pattern for goes into `Assumptions` (you'll be inventing it; that needs to be visible).
+4. **Re-emit the six-section output** with the consolidated `Current understanding` before moving to Phase 3.
+
+The point isn't "more agents = better." It's that wide inspection eats the main context window and the per-turn output format eats it again every turn — the council pushes the reading off-window so the executional phase still has room to breathe.
+
+**Library API check.** If the plan depends on a specific third-party library / framework symbol (e.g. EF Core, Prisma, NextAuth, Stripe SDK), and the version is pinned in this repo, query `context7` for the current docs before drafting the plan. Training-data API knowledge can be a major version behind.
+
+### Phase 3 — Plan (gate on approval)
+
+Draft the `Plan` section as a numbered list of concrete, verifiable steps. Each step is one logical change with a clear validation method.
+
+Then enter Plan Mode (`EnterPlanMode`) and present the plan along with the rest of the per-turn output. Call `ExitPlanMode` and **wait**. Do not write a single file until the user approves the plan.
+
+If the user pushes back, revise and re-present. Do not partial-implement against an unapproved plan.
+
+### Phase 4 — Execute incrementally
+
+Walk the plan one step at a time. For each step:
+
+1. **Make the smallest change that completes the step.** No drive-by refactors, no "while I'm here" fixes, no batched edits across multiple steps.
+2. **Validate immediately.** Run the test, build, type-check, lint, curl the endpoint, or load the page — whichever signal is appropriate for that step. If there's no automated signal at all, say so explicitly in `Progress`; don't pretend there is one.
+3. **Tick the checkbox** with a one-line evidence note (`tests pass`, `dotnet build green`, `200 OK with expected body`).
+4. **Re-emit the full per-turn output** before moving to the next step.
+
+When a validation fails:
+
+- Do not move on.
+- Add the failure mode to `Risks`.
+- Diagnose in place (one focused investigation, not a tangent). If it turns into a real debugging session, suggest dropping into `diagnose` and pausing this skill.
+
+When you find new files you need to read mid-execution, add them to `Files to inspect` rather than reading silently. The list is the audit trail.
+
+### Phase 5 — Final validation and report
+
+When every checkbox is ticked:
+
+- Re-run the full validation suite for the task (tests + build + any acceptance criteria from `Current understanding`).
+- Emit one last full per-turn output where `Progress` is entirely `[x]`, `Assumptions` is empty (or each remaining assumption is justified as out-of-scope), and `Risks` lists anything the user should know about that wasn't part of the task.
+- End with one short paragraph: what changed, what to run, what's deliberately not done.
+
+## Anti-patterns
+
+- ❌ Omitting sections "because nothing changed". The structure exists precisely so a future session can resume — write `_(none yet)_` instead.
+- ❌ Skipping inspection because the answer "looks obvious". The cost of being wrong is much higher than the cost of one extra `Read`.
+- ❌ Batching multiple plan steps into a single change and ticking them together. The validation-per-step is the discipline; collapsing it loses the value.
+- ❌ Treating an unconfirmed inference as `Current understanding`. Anything you're betting on without evidence is an `Assumption` until proven.
+- ❌ Drifting from the strict header set ("here's a quick update" prose-only turns). One ad-hoc turn becomes ten.
+- ❌ Running this skill on a fuzzy spec. Stop and route to [`plan-and-build`](../plan-and-build/SKILL.md) — its Phase 1 grill is what's missing.
+- ❌ Exiting Plan Mode while the plan still has open questions or assumptions that materially change the design.
+- ❌ Continuing past a failed validation. A red test is a Phase-4 stop, not a TODO for later.
+- ❌ Inventing new abstractions when an existing pattern in the repo would have answered the same need. The inspection phase exists to prevent this.
+- ❌ Convening the inspection council for a 3-file task. Ceremony for its own sake. Inline reads are the default — escalate only when the inspection set genuinely spans multiple layers.
+- ❌ Spawning the inspection sub-agents serially instead of in parallel — one message, N `Agent` calls. Serial defeats the context-protection rationale.
+- ❌ Letting a sub-agent slice overlap with another's. If two slices would re-read the same files, merge them first.
+- ✅ Same six headers every turn, one step at a time, one validation per step, assumptions tracked explicitly until confirmed or killed.
+
+## Examples
+
+### Example 1: A concrete task with a defined scope
+
+**User:** "/task-executor — Work on task: Add a Stripe subscriptions webhook endpoint that records subscription state changes in our existing `Subscriptions` table."
+
+**Claude:**
+
+1. **Phase 1 — Understand.** First turn opens with all six headers. `Goal` restates the task. `Current understanding` notes "endpoint must verify Stripe signature; state changes recorded in existing `Subscriptions` table". `Assumptions` lists "endpoint lives under `/api/webhooks/stripe`" (not yet confirmed) and "no new table needed".
+2. **Phase 2 — Inspect.** Populates `Files to inspect` with `BillingService.cs`, `Subscriptions.cs` (the entity), `appsettings.json` (for the webhook secret), one existing webhook endpoint as a pattern reference. Reads them in parallel, then moves each into `Current understanding` with a one-line takeaway. Confirms the assumption about the route (or revises it).
+3. **Phase 3 — Plan.** Enters Plan Mode. Plan lists: (1) add `StripeWebhookController` with signature verification, (2) extend `BillingService.HandleSubscriptionEvent`, (3) wire DI, (4) append three NUnit tests to `BillingServiceTests`, (5) run `dotnet test`, (6) run `dotnet build`. Calls `ExitPlanMode` and waits.
+4. **Phase 4 — Execute.** Step (1): writes the controller, runs `dotnet build`, ticks `[x] controller scaffolded — build green`. Re-emits all six sections. Step (2): writes the service method, writes the first test, runs `dotnet test` — red for the right reason, then green after implementation, ticks. Continues one at a time.
+5. **Phase 5 — Report.** Final turn shows every step `[x]`, lists files written, gives the exact command for the user to test the endpoint locally with Stripe CLI.
+
+### Example 2: User invokes the skill on a fuzzy spec
+
+**User:** "/task-executor — Build the subscription management area."
+
+**Claude:** First turn opens with the six headers anyway. `Goal` restates what the user said. `Current understanding` flags that "subscription management area" is undefined (pages? roles? actions? entry point?). `Risks` lists three or four concrete ambiguities. Then a single short paragraph at the end: "This spec is too fuzzy for `task-executor`. Recommend dropping into [`plan-and-build`](../plan-and-build/SKILL.md) — its Phase 1 grill is what's needed before this skill's discipline applies. Want me to switch?"
+
+### Example 3: A validation fails mid-execution
+
+**User:** Mid-task. Claude has ticked steps 1–3 and just ran the tests for step 4.
+
+**Claude:** Re-emits all six sections. `Progress` shows step 4 unchecked with a one-line note `tests failed — NullReferenceException at BillingService.cs:84`. `Risks` adds the failure. `Current understanding` notes the call site. Diagnoses in place — one targeted read, one minimal fix, re-runs. If the fix is one-line and obvious, ticks the step and continues. If the failure spreads or the cause is non-obvious, suggests pausing this skill and dropping into [`diagnose`](../diagnose/SKILL.md).
+
+## Notes
+
+- This skill composes downward from [`plan-and-build`](../plan-and-build/SKILL.md): once `plan-and-build` lands an approved plan, you can hand the steps to `task-executor` for the disciplined incremental execution. The skills overlap in Plan Mode usage but differ in upstream phases — `plan-and-build` interviews and detects stack; `task-executor` assumes the spec is given and forces output discipline every turn.
+- The six-header format is deliberately rigid. It's the part of the skill that loses value the moment you let it slip — one ad-hoc turn breaks the contract.
+- If the task is small enough that the six-section output dwarfs the actual work, the task is too small for this skill. Just do it.