Maintain Evidence-Gated API Transition Governance

Required inputs

Have these details available before following the usage instructions.

• Current and replacement API contracts, versions, implementations, SDKs, documentation, and compatibility requirements
• Living client inventory with client owners, environments, versions, traffic, business criticality, migration state, and evidence status
• Telemetry definitions, observation windows, environment coverage, adoption measures, and known blind spots
• Lifecycle policy, proposed dates, contractual obligations, communication requirements, support capacity, and decision roles
• Migration tests, client validation, exceptions, compatibility mechanisms, rollback or restoration options, and unresolved risks
• API owner, client owners, product owner, legal reviewer, security reviewer, support owner, and release owner

How to use this Skill

When to use:
- Governing a public, partner, internal, or legacy API transition across proposal, announcement, migration, restricted use, sunset, and retirement states.
- Reassessing client readiness after contract, implementation, SDK, telemetry, migration, exception, or schedule changes.
- Maintaining evidence and decision gates over repeated transition reviews rather than producing a one-time plan.

When not to use:
- Debugging one client integration with no lifecycle transition.
- Treating emergency shutdown or incident containment as a normal deprecation process.
- Declaring an API unused without client, owner, telemetry, and environment evidence.
- Authorizing contract changes, customer commitments, production routing changes, or endpoint shutdown outside the accountable roles.

Instructions:
Reusable transition-governance method:
1. Maintain a version and contract inventory that records current and replacement interfaces, implementations, SDKs, documentation, environments, behavioral invariants, known differences, and evidence freshness.
2. Assign every API version a lifecycle state with entry criteria, required evidence, accountable decision roles, allowed actions, exit criteria, and next review date.
3. Maintain a living client register covering verified clients, likely clients, unknown ownership, business criticality, migration path, current state, blockers, target date, validation evidence, and next action.
4. Maintain compatibility evidence for success, error, authentication, permission, rate-limit, retry, ordering, pagination, side-effect, and recovery behavior relevant to the transition.
5. Track migration evidence separately from plans: observed legacy use, replacement use, successful business workflows, client validation, error changes, telemetry coverage, and blind spots.
6. Maintain communication state by audience, channel, required content, draft or approved status, send evidence, support route, contractual requirement, and owner.
7. Govern exceptions as time-bound records with scope, reason, client owner, risk, compensating control, approver, expiry, escalation, and closure evidence.
8. Re-run the appropriate migration gate at each lifecycle transition. Evaluate critical-client status, compatibility tests, telemetry sufficiency, unresolved exceptions, support readiness, stop conditions, and legal or contractual constraints.
9. Maintain rollback or restoration feasibility, operational steps, monitoring, decision triggers, and known points where recovery would be slow, incomplete, or impossible.
10. Record each lifecycle decision with evidence used, unknowns, dissent, authorization, effective date, conditions, next action, and next review. Use AMO-P-000238 as source grounding for deeper repository and migration analysis, not as a substitute for the living governance state.

Expected output:
A living API transition governance record containing the contract and version inventory, lifecycle-state register, client migration register, compatibility evidence, telemetry and communication state, exception ledger, repeated gate results, sunset criteria, recovery readiness, unresolved risks, accountable roles, and versioned decision records.

Constraints and boundaries:
- Do not claim that a client migrated, a notice was approved or sent, telemetry was inspected, a test passed, or an endpoint changed without corresponding evidence.
- Do not treat a target date or aggregate traffic decline as sufficient sunset evidence.
- Preserve secrets, credentials, personal data, confidential contracts, and restricted client information.
- Contractual interpretation belongs to the legal reviewer; compatibility and lifecycle ownership belong to the API owner; client evidence belongs to the relevant client owner; product commitments belong to the product owner; security exceptions belong to the security reviewer; production retirement belongs to the release owner.
- Preserve backward compatibility unless an explicitly authorized break is recorded with affected clients, mitigations, recovery limits, and acceptance criteria.

Powered by an Amo.ng Prompt

API Deprecation and Client Migration Playbook

Open the linked prompt to use the instructions that power this Skill.

Completion criteria

Complete when:
- API contracts, versions, lifecycle states, behavioral invariants, implementations, and evidence freshness are recorded.
- Every known client has an owner or ownerless flag, migration state, evidence status, blocker, target, and next action.
- Compatibility and migration evidence covers the relevant success, error, authentication, permission, retry, side-effect, and business-workflow behavior.
- Telemetry records its source, window, environment coverage, denominator, blind spots, and current gate result.
- Communications and exceptions have explicit status, owners, approvals, expiry or next review, and closure evidence.
- The current lifecycle gate states pass, hold, revise, or stop with measurable criteria, recovery readiness, unresolved risks, authorization, and the next review date.