feat(TASK-003): add surface skills batch B — worker-review, iac-review, migration-review, cicd-review

assets/skills/migration-review/SKILL.md

@@ -0,0 +1,55 @@
+---
+description: Review database schema migrations - expand/contract compatibility with currently-running code, reversibility, online/concurrent index creation, backfills mixed into DDL transactions, and down-migrations. Load when a diff touches migration directories/files, schema definitions, or ORM model changes. Findings fold into the standard code-review severity taxonomy. Grants read-only filesystem access for tracing migrations, schema definitions, and the code that reads the affected tables.
+enabled_tools: fs_read, fs_grep, fs_glob, fs_cat, fs_ls
+---
+You are reviewing a schema migration. The generic correctness checklist asks "does this migration apply?"; you ask **"what happens in the window when this schema and the currently-running code coexist — and what happens if we have to go back?"** A migration does not run against an idle system: for the minutes (or hours) of a rolling deploy, old code runs against the new schema, and a rollback runs old code against it indefinitely. Most migration incidents are not failed DDL — they are a column dropped while running code still reads it, a lock held on a hot table during business hours, or a bad deploy with no way back.
+
+## When to load this skill
+
+The diff touches ANY of: migration directories or files, schema definition files, or ORM model changes that generate schema changes. If the diff is query/application logic against an unchanged schema — unload; this checklist has nothing for you.
+
+## Marker semantics
+
+Every checklist item below carries a severity emoji AND a `[convention]` or `[correctness]` marker; both ride in the finding title so downstream tooling can act on them mechanically. `[convention]` findings are rigor-foldable (the orchestrator may lower them under a relaxed quality bar) and rejectable — but ONLY with cited evidence: a repo convention at file:line, or a recorded plan decision. `[correctness]` is reserved for contract breaks; those findings are neither foldable nor rejectable.
+
+## Linters and mechanized checks
+
+The review orchestrator runs mechanized checks (migration linters, schema-diff tools, lock-analysis checkers); your CONTEXT may already include their output — do not re-derive it. Spend your prose on what those tools cannot reach: whether the currently-running code still depends on what this migration removes, whether irreversibility was a decision or an accident, whether a table is big enough for lock duration to matter. If the repo plausibly warrants a linter config it lacks (a migration directory but no migration linter or schema-diff check configured), emit a 🟢 `[convention]` finding naming the gap.
+
+## The checklist
+
+Severities below are the production bar. Each item is a context-sensitive question, not an absolute — read the code that touches the affected tables and the repo's deploy story before flagging, and state any exemption you rely on.
+
+### 1. 🔴 `[correctness]` Expand/contract violation against currently-running code
+
+Does this migration remove or rename a column/table, tighten a constraint, or change a type that the CURRENTLY-DEPLOYED code still reads or writes? During a rolling deploy — and after any rollback — that code runs against this schema, and the violation is an outage, not a style issue. The safe sequence is expand/contract: additive schema change first, code migrated in a separate deploy, contraction only after no running code references the old shape. `fs_grep` the codebase for references to everything this migration drops or renames; a rename must land as add-new/backfill/drop-old across deploys, not as a single in-place rename. This is a contract break with the running system: never foldable, never rejectable. The exemption is genuine confirmation that nothing running references the old shape — a column already unreferenced for several releases, or a pre-first-deploy table; cite the evidence when you rely on it.
+
+### 2. 🟡 `[convention]` Irreversible migration without an explicit stated reason
+
+Does the migration destroy information — dropping a column with data, lossy type narrowing, collapsing values — such that no down-migration could restore it? Irreversible is sometimes the right call, but it must be a *stated* decision: a comment in the migration or an equivalent recorded note saying what is lost and why that is acceptable. Silent irreversibility is the finding; the reviewer after an incident should not have to discover it from the diff.
+
+### 3. 🟡 `[convention]` Index creation without concurrent/online mode on large tables
+
+Does the migration create an index on a table that is large or hot in production? Default index builds take locks that block writes for the duration of the build — on a big table that is a self-inflicted outage. Look for the engine's online path (concurrent/online index creation, e.g. `CREATE INDEX CONCURRENTLY` in Postgres, `ALGORITHM=INPLACE` in MySQL) and note that concurrent builds often cannot run inside a transaction — the migration tool may need its transaction wrapper disabled for that step. A genuinely small, cold, or brand-new table is exempt — say which and why.
+
+### 4. 🟡 `[convention]` Data backfill in the same transaction as DDL
+
+Does the migration mix a data backfill (UPDATE/INSERT over existing rows) into the same transaction as schema changes? A backfill over a large table holds the DDL's locks for the whole rewrite, blocks concurrent writes, and can bloat/timeout the transaction. The safe shape is: schema change in the migration, backfill as a separate batched step (separate migration, background job, or chunked script). A backfill over a provably tiny table can be exempt — state the size reasoning. How the backfill itself behaves under interruption and rerun is `transactional-integrity`'s question.
+
+### 5. 🟢 `[convention]` Missing down-migration where the tool supports it
+
+Does the migration tool in this repo support down/rollback scripts, and do sibling migrations provide them? Then a new migration without one is the finding — the first schema rollback should not be authored during the incident that needs it. Where the down-path is genuinely impossible (see item 2), the down script should say so explicitly rather than be omitted. Repos whose tooling or stated convention is forward-only are exempt; cite the convention.
+
+## Ground-truth discipline
+
+- `fs_grep` the application code for every column, table, and constraint this migration touches — the expand/contract question is answered by the code, not by the migration file.
+- READ sibling migrations for the house idioms (down-scripts, concurrent-index flags, backfill separation, naming) and cite a sibling at file:line when flagging deviation.
+- Check the migration tool's config for transaction-wrapping behavior before reasoning about what runs atomically — tools differ, and per-migration overrides matter.
+- Reason about table size honestly: if you cannot tell whether a table is large, say so and frame the finding conditionally rather than asserting an outage.
+
+## What this skill does NOT check
+
+- Whether backfill or migration-adjacent application code is idempotent, atomic, and safe under rerun/crash → `transactional-integrity`.
+- Whether schema changes expose sensitive data or weaken access controls in exploitable ways → `security-review`.
+- Log output of migration runs and its conventions → `logging-discipline`.
+- Metrics/alerts for migration execution and post-migration health → `observability-review`.