deprecation-and-migration

Plan and execute safe deprecation and migration of APIs, schemas, and systems.

Updated Aug 5, 2026
One-click install
npx skills add https://github.com/ahsanghalib/ai-workflow --skill deprecation-and-migration-ahsanghalib
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: deprecation-and-migration
Source: https://github.com/ahsanghalib/ai-workflow/tree/main/skills/deprecation-and-migration
Command: npx skills add https://github.com/ahsanghalib/ai-workflow --skill deprecation-and-migration-ahsanghalib

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Retiring an API, library, feature, or schema without breaking consumers is risky: hidden callers, destructive schema changes, and irreversible data loss can turn a simple cleanup into an outage. This Skill provides a structured workflow for deprecating old behavior and migrating consumers safely, with evidence-based verification before removal. ## Core Features & Use Cases - Consumer Inventory and Impact Analysis: Maps all callers, integrations, configurations, and runtime consumers using static search combined with tests, telemetry, logs, and owner confirmation. - Reversible Cutover Patterns: Guides selection of adapters, strangler patterns, feature flags, compatibility layers, and the expand-migrate-contract approach for schema changes. - Incremental Migration with Approval Gates: Migrates consumers in thin slices with verification at each step, and pauses for explicit approval before changing public contracts, production data, or destructive state. - Use Case: You need to retire a legacy REST endpoint used by multiple services. The Skill helps you inventory consumers, publish a migration guide with a support window, move each consumer with rollback evidence, and remove the old code only after verifying zero active usage. ## Quick Start Ask the assistant to plan the deprecation of the legacy v1 payments API and migrate all consumers to v2 with a reversible cutover strategy.

Frequently Asked Questions about deprecation-and-migration

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I safely deprecate an API without breaking consumers?▼

Inventory all consumers using static search plus telemetry, logs, and owner confirmation, then publish a migration guide with a support window. Migrate consumers in thin slices with verification, and remove the old API only after evidence shows zero active usage.

How to migrate a database schema without downtime?▼

Use the expand-migrate-contract pattern: add the new schema shape first, support old and new code together, backfill data in bounded batches, switch reads, then remove the old shape in a later separately approved change. Never couple destructive schema changes to the first code release.

When should I use advisory versus compulsory deprecation?▼

Default to advisory deprecation when the old path is stable and migration is optional, providing warnings and a target date. Use compulsory deprecation only when security, operational, legal, or maintenance risk justifies a hard deadline with migration tooling and support.

Can I verify zero usage of old code with a repository search alone?▼

No, a repository search alone is insufficient for surfaces with external consumers. Combine static evidence with tests, telemetry, logs, dependency analysis, or owner confirmation before claiming zero usage and removing code.

What are the risks of destructive schema changes during migration?▼

A rollback of application code cannot restore deleted data, so destructive changes must be decoupled from code releases. Define backup/restore or forward-repair evidence for data that cannot be reversed by a normal rollback.