[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7CSSA58VMQ652GQSE0T298V":3,"skill-same:01M7CSSA58VMQ652GQSE0T298V":49},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":26,"commitSha":27,"skillDirectory":28,"forksCount":29,"repositoryHtmlUrl":30,"repositoryHomepageUrl":31,"ownerHtmlUrl":32,"ownerBlogUrl":6,"ownerDescription":33,"updatedAt":34,"install":35,"resources":48},"01M7CSSA58VMQ652GQSE0T298V","migration-and-contract-review",null,"Use when a diff or design adds or changes a DB migration, an endpoint or DTO, an event payload, or a shared type with consumers","makifbaysal\u002Ftasktrooper","makifbaysal","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F25031940?v=4","01M7CRG3ZCSYZSSEVDMW3DEYC8","Mehmet Akif Baysal","01M7CRG401FJ8YAXH5ER730XYV",122,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fsystem-architect\u002Fskills\u002Fmigration-and-contract-review\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: migration-and-contract-review\ncategory: quality\ndescription: Use when a diff or design adds or changes a DB migration, an endpoint or DTO, an event payload, or a shared type with consumers\nsource: sbdchd\u002Fsquawk docs (Apache-2.0), ankane\u002Fstrong_migrations (MIT), Google AIP-180 (CC BY 4.0), adapted\n---\n# Migration & Contract Review\n\n## Why It Matters Here\n\nA production rollback reverts the merge commit — it does **not** undo the schema. The old code has to keep running against the new schema until a human decides otherwise, and the system already flags a schema-touching task for a mandatory stage deploy. A migration or contract reviewed only for \"does it run\" and not \"does the PREVIOUS release's code still work against it\" is an outage waiting for the next rollback.\n\nPair with migration-safety (backend-developer, same rules from the authoring side) and spec-authoring's Security & data \u002F Decision record sections for the design-time version of this.\n\n## Blocking Checks (Important or Critical)\n\n**Editing an applied migration.** A migration already run on any environment is immutable; a fix is a new migration.\n- ❌ editing `0042_add_status.sql` after it merged.\n- ✅ `0051_fix_status_default.sql` that corrects it.\n\n**A stub or empty down\u002Frollback migration.** If it can't really be undone, say so and give the operational alternative instead of a down migration that lies.\n\n**Drop, rename or retype of a column or table still read by deployed code.**\n- ❌ `ALTER TABLE tasks DROP COLUMN legacy_status;` in the same task that stops writing it.\n- ✅ stop writing it (task N), deploy, confirm no reads remain (`grep_code`\u002Fconsumer check), THEN drop it (task N+1, `deploy_depends_on: [\"N\"]`).\n\n**`ADD COLUMN … NOT NULL` with no default**, or a **volatile default** (rewrites the whole table).\n- ❌ `ALTER TABLE tasks ADD COLUMN priority int NOT NULL;`\n- ✅ `ALTER TABLE tasks ADD COLUMN priority int NOT NULL DEFAULT 0;` — a constant default on PG11+ does not rewrite the table.\n\n**`CREATE INDEX` without `CONCURRENTLY`** on a table already carrying rows, or `CONCURRENTLY` used inside a transaction \u002F a multi-statement file the repo's migration runner wraps in one (check how the runner executes a file before assuming `CONCURRENTLY` is safe there).\n- ❌ `CREATE INDEX idx_tasks_status ON tasks(status);` on a live table — takes a write lock for the build.\n- ✅ `CREATE INDEX CONCURRENTLY idx_tasks_status ON tasks(status);`, run outside a transaction.\n\n**A FK or CHECK added without `NOT VALID` + a later `VALIDATE`.**\n- ❌ `ALTER TABLE tasks ADD CONSTRAINT fk_project FOREIGN KEY (project_id) REFERENCES projects(id);` — locks and scans the whole table.\n- ✅ `ADD CONSTRAINT … NOT VALID;` then, in a later step\u002Fmigration, `VALIDATE CONSTRAINT fk_project;`.\n\n**`SET NOT NULL` on an existing column** with no prior validated `CHECK (col IS NOT NULL)` (PG12+ lets the planner skip the full scan once that check is validated).\n\n**A data backfill inside the schema migration**, unbatched. Backfill in application code or a batched script, not a single blocking UPDATE in the DDL migration.\n\n**A new query path added with no supporting index** — works in dev on a handful of rows, locks up in production.\n\n## Contract Checks\n\n- **Additive is safe:** a new optional response field, a new endpoint, a new optional request field with a default.\n- **Breaking needs every consumer updated and ordered:** a renamed\u002Fremoved field, a changed type or status code, a new REQUIRED request field, a changed default page size, a changed enum's meaning.\n  - AIP-180: *\"Old clients must be able to work against newer servers\"* — source, wire and semantic compatibility all have to hold, not just \"it compiles.\"\n- **Mobile clients cannot be force-updated.** Anything an already-installed app reads stays readable until a later, separate contract task ships and enough time has passed — never break it in the same task that adds the new shape.\n- **Find consumers** with `list_links(component, direction:\"in\")`, then `grep_code` in the cloned consumer repo (technical-analysis-workflow's cross-repo clone procedure) for the exact field\u002Fendpoint.\n- **Error shape and status codes are part of the contract** — changing a 404 to a 200-with-null, or a flat error body to a nested one, breaks a consumer's error handling exactly like a renamed field.\n\n## Design-Side Application (spec-authoring)\n\nAny schema or contract change in the design gets: the expand step and the contract (breaking) step as SEPARATE tasks in the `split`, a `before_deploy` entry on the expand task (\"migration N applied on stage\"), and a `rollback_plan` that states plainly that the schema stays and names what still reads it. The contract-breaking task carries `deploy_depends_on` on every consumer-update task.\n\n## Common Mistakes\n\n- Treating \"the migration ran in the task's dev DB\" as proof it's safe in production — a live table with real row counts behaves differently under a table rewrite or a non-concurrent index build.\n- Reviewing the SQL in isolation from the code that reads the table — a column drop is safe only once nothing reads it, which is a code fact, not a SQL fact.\n- Accepting \"the mobile team will update eventually\" as cover for a breaking contract change shipped now.\n\n## Red Flags\n\n- A single migration file both drops a column and the diff still has a reader for it (`grep_code` the old field name).\n- `NOT NULL` added to an existing column with no earlier `CHECK` step.\n- A renamed REST field with no corresponding `blocked_by`\u002F`deploy_depends_on` on the consuming repositories' tasks.\n- `before_deploy`\u002F`rollback_plan` left empty on a task that `HasMigration`.\n","# Migration & Contract Review\n\n## Why It Matters Here\n\nA production rollback reverts the merge commit — it does **not** undo the schema. The old code has to keep running against the new schema until a human decides otherwise, and the system already flags a schema-touching task for a mandatory stage deploy. A migration or contract reviewed only for \"does it run\" and not \"does the PREVIOUS release's code still work against it\" is an outage waiting for the next rollback.\n\nPair with migration-safety (backend-developer, same rules from the authoring side) and spec-authoring's Security & data \u002F Decision record sections for the design-time version of this.\n\n## Blocking Checks (Important or Critical)\n\n**Editing an applied migration.** A migration already run on any environment is immutable; a fix is a new migration.\n- ❌ editing `0042_add_status.sql` after it merged.\n- ✅ `0051_fix_status_default.sql` that corrects it.\n\n**A stub or empty down\u002Frollback migration.** If it can't really be undone, say so and give the operational alternative instead of a down migration that lies.\n\n**Drop, rename or retype of a column or table still read by deployed code.**\n- ❌ `ALTER TABLE tasks DROP COLUMN legacy_status;` in the same task that stops writing it.\n- ✅ stop writing it (task N), deploy, confirm no reads remain (`grep_code`\u002Fconsumer check), THEN drop it (task N+1, `deploy_depends_on: [\"N\"]`).\n\n**`ADD COLUMN … NOT NULL` with no default**, or a **volatile default** (rewrites the whole table).\n- ❌ `ALTER TABLE tasks ADD COLUMN priority int NOT NULL;`\n- ✅ `ALTER TABLE tasks ADD COLUMN priority int NOT NULL DEFAULT 0;` — a constant default on PG11+ does not rewrite the table.\n\n**`CREATE INDEX` without `CONCURRENTLY`** on a table already carrying rows, or `CONCURRENTLY` used inside a transaction \u002F a multi-statement file the repo's migration runner wraps in one (check how the runner executes a file before assuming `CONCURRENTLY` is safe there).\n- ❌ `CREATE INDEX idx_tasks_status ON tasks(status);` on a live table — takes a write lock for the build.\n- ✅ `CREATE INDEX CONCURRENTLY idx_tasks_status ON tasks(status);`, run outside a transaction.\n\n**A FK or CHECK added without `NOT VALID` + a later `VALIDATE`.**\n- ❌ `ALTER TABLE tasks ADD CONSTRAINT fk_project FOREIGN KEY (project_id) REFERENCES projects(id);` — locks and scans the whole table.\n- ✅ `ADD CONSTRAINT … NOT VALID;` then, in a later step\u002Fmigration, `VALIDATE CONSTRAINT fk_project;`.\n\n**`SET NOT NULL` on an existing column** with no prior validated `CHECK (col IS NOT NULL)` (PG12+ lets the planner skip the full scan once that check is validated).\n\n**A data backfill inside the schema migration**, unbatched. Backfill in application code or a batched script, not a single blocking UPDATE in the DDL migration.\n\n**A new query path added with no supporting index** — works in dev on a handful of rows, locks up in production.\n\n## Contract Checks\n\n- **Additive is safe:** a new optional response field, a new endpoint, a new optional request field with a default.\n- **Breaking needs every consumer updated and ordered:** a renamed\u002Fremoved field, a changed type or status code, a new REQUIRED request field, a changed default page size, a changed enum's meaning.\n  - AIP-180: *\"Old clients must be able to work against newer servers\"* — source, wire and semantic compatibility all have to hold, not just \"it compiles.\"\n- **Mobile clients cannot be force-updated.** Anything an already-installed app reads stays readable until a later, separate contract task ships and enough time has passed — never break it in the same task that adds the new shape.\n- **Find consumers** with `list_links(component, direction:\"in\")`, then `grep_code` in the cloned consumer repo (technical-analysis-workflow's cross-repo clone procedure) for the exact field\u002Fendpoint.\n- **Error shape and status codes are part of the contract** — changing a 404 to a 200-with-null, or a flat error body to a nested one, breaks a consumer's error handling exactly like a renamed field.\n\n## Design-Side Application (spec-authoring)\n\nAny schema or contract change in the design gets: the expand step and the contract (breaking) step as SEPARATE tasks in the `split`, a `before_deploy` entry on the expand task (\"migration N applied on stage\"), and a `rollback_plan` that states plainly that the schema stays and names what still reads it. The contract-breaking task carries `deploy_depends_on` on every consumer-update task.\n\n## Common Mistakes\n\n- Treating \"the migration ran in the task's dev DB\" as proof it's safe in production — a live table with real row counts behaves differently under a table rewrite or a non-concurrent index build.\n- Reviewing the SQL in isolation from the code that reads the table — a column drop is safe only once nothing reads it, which is a code fact, not a SQL fact.\n- Accepting \"the mobile team will update eventually\" as cover for a breaking contract change shipped now.\n\n## Red Flags\n\n- A single migration file both drops a column and the diff still has a reader for it (`grep_code` the old field name).\n- `NOT NULL` added to an existing column with no earlier `CHECK` step.\n- A renamed REST field with no corresponding `blocked_by`\u002F`deploy_depends_on` on the consuming repositories' tasks.\n- `before_deploy`\u002F`rollback_plan` left empty on a task that `HasMigration`.\n",{"name":5,"source":24,"category":25,"description":7},"sbdchd\u002Fsquawk docs (Apache-2.0), ankane\u002Fstrong_migrations (MIT), Google AIP-180 (CC BY 4.0), adapted","quality","main","910394a0b6db9fc8c9a8f36328ec421d3ebd8b38","catalog\u002Fagents\u002Fsystem-architect\u002Fskills\u002Fmigration-and-contract-review",18,"https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper","https:\u002F\u002Ftasktrooper.ai","https:\u002F\u002Fgithub.com\u002Fmakifbaysal","Senior Software Developer","2026-11-15 04:50:29",{"source":8,"skillName":5,"commands":36,"prompt":46,"zipAvailable":47},[37,40,43],{"tool":38,"command":39},"npx","npx skills add makifbaysal\u002Ftasktrooper --skill migration-and-contract-review",{"tool":41,"command":42},"bunx","bunx skills add makifbaysal\u002Ftasktrooper --skill migration-and-contract-review",{"tool":44,"command":45},"pnpm","pnpm dlx skills add makifbaysal\u002Ftasktrooper --skill migration-and-contract-review","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fsystem-architect\u002Fskills\u002Fmigration-and-contract-review\u002FSKILL.md",true,[],[50,56,63,70,77,84],{"skillNo":51,"name":52,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":53,"categories":54,"keywords":55,"publishedAt":19},"01M7CSVEPQW6J6TD6CS2T5FPNZ","visual-craft","https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fui-designer\u002Fskills\u002Fvisual-craft\u002FSKILL.md",[],[],{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":19},"01M7CSVAQG91ETHQ0HBNZDG5FR","ux-copy","Use when you write any words a user reads in a mockup or a hand-off - content language and voice, buttons, labels, errors, empty states, confirmations, numbers and dates, and the longest-string check","https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fui-designer\u002Fskills\u002Fux-copy\u002FSKILL.md",[],[],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":19},"01M7CSV6H0J38659NDXHJQ8396","screen-mockup-html","Use when you draw screens as the design task's HTML mockup - ONE canvas document holding every screen and every variant side by side, the sanitizer-safe recipe, phone and wide frames, the states grid, static control states, and the loopback self-check with screenshots at 375, 768 and 1440 attached to the task","https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fui-designer\u002Fskills\u002Fscreen-mockup-html\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":19},"01M7CSV3JFRF3BM3XK52M7YEYR","performance-awareness","How the performance score moves for your role. Use when the score context shows a declining trend, or before handing off work you have not self-checked against every criterion.","https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fui-designer\u002Fskills\u002Fperformance-awareness\u002FSKILL.md",[],[],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":19},"01M7CSTZDH00YRF5SCT7BRT9QD","design-variants","Use when a screen design needs variants - how many, variants as side-by-side rows on the one canvas, what makes two variants genuinely different, recommending one, how the human's choice is read, and narrowing to the chosen one in revision","https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fui-designer\u002Fskills\u002Fdesign-variants\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":19},"01M7CSTV6P3SM3PAE28DB0RF77","design-system-authoring","Use when you derive, change or extend a design system - where tokens live per stack, the DTCG token tree, role-based names for both themes, base vs layer vs drift, the DESIGN.md section order, the inventory format, the contrast check and the lint every proposal returns","https:\u002F\u002Fgithub.com\u002Fmakifbaysal\u002Ftasktrooper\u002Fblob\u002Fmain\u002Fcatalog\u002Fagents\u002Fui-designer\u002Fskills\u002Fdesign-system-authoring\u002FSKILL.md",[],[]]