Skip to content

dvy1987/agent-loom / .agents/skills/api-deprecation-and-migration

api-deprecation-and-migration

Verified

Deprecate APIs, features, or systems safely — announce, migrate consumers, sunset on a timeline, and document alternatives. Load when removing an old API, migrating users between implementations, sunsetting a feature, or the user asks about deprecation policy, migration guides, or breaking changes. Not for deleting dead code with zero consumers (use code-simplification). Distinct from meta `deprecate-skill` (skill library retirement).

API Deprecation and Migration

Code is a liability. Deprecation removes systems that no longer earn their keep; migration moves consumers safely to replacements.

Hard Rules

  • Replacement before removal — working alternative with docs and migration path.
  • Default advisory — warnings and timelines; compulsory only for security or unsustainable cost.
  • Quantify consumers — usage metrics, client lists, or repo search before dates.
  • Hyrum's Law — undocumented behavior will be depended on; plan for stragglers.
  • Telemetry on migration — track who still calls deprecated surfaces.

Workflow

Step 1 — Deprecation decision

Answer: unique value remaining? consumer count? replacement ready? migration cost vs maintenance cost?

Step 2 — Announce

Publish notice: what, why, timeline, replacement, migration guide link, contact.

Step 3 — Migrate

Provide codemods, dual-write/read periods, feature flags, or versioned endpoints as appropriate.

Step 4 — Sunset

After deadline: return structured errors on old surface; keep read-only tombstone period if needed.

Step 5 — Remove and document

Delete code; update changelog; postmortem on straggler pain for next time.


Advisory vs compulsory

TypeWhenMechanism
AdvisoryStable old path, low riskDocs + warnings + metrics
CompulsorySecurity, blocking progressHard deadline + tooling + support

When NOT to use

  • Internal dead code with zero callers (delete with tests)
  • Retiring a skill from agent-loom library (deprecate-skill instead)

Gotchas

  • Announcing without migration guide guarantees support churn.
  • Breaking changes in patch versions destroy trust.
  • Dual-write without reconciliation causes data drift.
  • "We'll remove it someday" with no metric never happens.

Common Rationalizations

ExcuseReality
"Nobody uses the old API"Check logs — Hyrum's Law says otherwise.
"Just delete it"Forced migrations without notice become incidents.
"We'll support both forever"Two systems = double security and cognitive cost.
"Migration guide is enough"Tooling and deadlines drive completion.
"Breaking change in minor is fine"Semver exists so clients can plan.

Output Format

## Deprecation plan — [surface]

Consumers: [count/evidence]
Replacement: [link]
Type: [advisory/compulsory]
Timeline: [dates]
Migration: [steps/tooling]
Removal criteria: [metric or date]

Examples


Verification

  • Replacement documented and production-proven
  • Consumer impact quantified
  • Timeline and notice published
  • Migration tooling or guide available
  • Telemetry proves traffic at zero before code removal

Red Flags

  • Sunset announced without working replacement and docs
  • Breaking change shipped in patch or minor version
  • Dual-write path has no reconciliation or drift checks
  • Deprecation timeline set without consumer usage evidence

Prune Log

Last pruned: 2026-07-04

  • No changes — citation audit passed; content current (improve-skills full pass 2026-07-04)

Impact Report

Surface: [name] | Consumers: [N]
Type: [advisory/compulsory] | Sunset: [date]
Migration: [ready/partial]
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall