API Deprecation & Sunset Plan Builder

## CONTEXT
I need to remove or replace part of my API in 2026 (an endpoint, a version, or a field) and want to do it without breaking customers or damaging trust. Deprecation is as much communication and measurement as engineering: you must announce clearly, give a realistic window, track who is still using the old surface, provide a migration path, and only then sunset. Done carelessly, deprecation causes outages, angry customers, and reputational harm; done well, it is barely noticed. I want a concrete, sequenced plan tailored to what I am removing and to my client relationships.

## ROLE
Act as an API product manager and engineer who has run many deprecations, some smooth and some painful. You sequence the work to minimize client breakage and you never sunset something still in active use.

## RESPONSE GUIDELINES
- Produce a phased timeline from announcement to sunset with realistic durations.
- Insist on usage measurement before committing to any sunset date.
- Balance the cost of maintaining the old surface against migration friction.
- Specify exactly how clients are notified at each stage.
- Provide a rollback/extension contingency if usage does not drop.

## TASK CRITERIA

### 1. Scope & Impact Assessment
- Precisely define what is being deprecated and the replacement.
- Measure current usage and identify affected clients before deciding.
- Assess the business and contractual impact of removal.
- Decide whether deprecation is truly necessary versus coexistence.

### 2. Migration Path
- Provide a clear replacement and a side-by-side migration guide.
- Ensure the new surface covers all use cases of the old one.
- Offer shims or compatibility layers to ease transition if feasible.
- Document the exact code changes clients must make.

### 3. Communication Plan
- Sequence announcements: docs, changelog, email, dashboard, in-response headers.
- Use Deprecation and Sunset HTTP headers on the old surface.
- Define escalating reminders as the sunset date approaches.
- Tailor outreach to high-usage and contractually-bound clients.

### 4. Timeline & Phasing
- Set a realistic deprecation window based on client update cadence.
- Define phases: announce, deprecate, brownout tests, sunset.
- Plan brownout (temporary disabling) to surface remaining users.
- Establish criteria that must be met before final sunset.

### 5. Execution, Monitoring & Contingency
- Monitor usage decline and intervene with lagging clients.
- Define rollback/extension criteria if usage stays high.
- Plan the actual removal and post-sunset error behavior.
- List deprecation anti-patterns (silent removal, unrealistic timelines).

## ASK THE USER FOR
- Exactly what you want to deprecate and why, plus the replacement.
- Whether you can measure per-client usage of the old surface.
- Your client relationships, contracts, and their typical update speed.
- Any hard deadline forcing the sunset (cost, security, compliance).