Deprecation Comms Plan Skill
Deprecations go wrong in two ways: too fast (customers get broken and churn angry) or too quiet (they find out when it breaks). This skill plans the wind-down as a communications program, not an announcement — enough runway, messaging matched to how much each customer depends on the thing, a real migration path, and a plan for the accounts that will need a human.
Working from a brief
Given what's being deprecated and why, produce the full plan — infer the risk tiers from usage and contract exposure. Right-size the runway to how hard the migration is (an internal flag flip is weeks; a public API is many months). If there's no migration path yet, flag that as a blocker before any announcement.
Required Inputs
Ask for (if not provided, else infer and label the assumption):
- What's being deprecated and why (cost, security, strategy, replaced-by)
- Who depends on it — rough usage, and which segments/contracts are exposed
- The replacement / migration path (or that there isn't one yet)
- Hard constraints — a forcing date (security, legal, contract), team capacity
Output Format
Deprecation policy in one line
The principle you're committing to (e.g. "announce → N months deprecated (works, warns) → sunset, with a migration path live before we announce").
Timeline
| Phase |
Date / window |
What changes |
What customers can still do |
| Announce |
|
nothing breaks; docs + warnings |
full use, start migrating |
| Deprecated |
|
warnings, no new adoption |
migrate |
| Sunset |
|
turned off |
must have migrated |
Include grace periods and any extension policy for large accounts.
Tiered messaging
Segmented by dependence, not one blast:
- Tier 1 — heavy/contractual users: proactive, human (CSM/AM), often a call + tailored plan.
- Tier 2 — active users: direct email + in-product warning + migration guide.
- Tier 3 — light/dormant: changelog, docs banner, deprecation headers.
For each: the core message (what, when, why, what to do), the ask, and the escalation path.
Migration guide outline
The structure of the how-to: before/after, step-by-step, code/config examples, a mapping table (old → new), FAQ, and where to get help.
Channel plan
Which channels fire at which phase — email, in-product, docs/changelog, API deprecation headers/Sunset header, status page, community/social — and the cadence (announce, reminders at intervals, final notice).
Internal escalation playbook
The at-risk account list, who owns each, the CSM talking points, the "customer can't migrate in time" decision tree, and the exception/extension approval path.
Quality Checks
Anti-Patterns
- Too little runway for the migration actually required
- A silent breaking change, or burying it in a changelog nobody reads
- Announcing before the migration path is live
- One-size messaging that treats a whale like a dormant free user
- No plan for the accounts that physically can't migrate in time
- "Why" that blames the customer or the old system instead of owning the change
Example Trigger Phrases
- "Winding down."
- "Plan a breaking change."
- "Migrate customers off a legacy path."
1---2name: deprecation-comms-plan3description: "Plan the communications for deprecating a product, API, endpoint, or feature that customers depend on. Use when winding down or sunsetting something, planning a breaking change, or migrating customers off a legacy path. Produces a staged timeline with grace periods, tiered customer messaging, a migration-guide outline, the channel plan, and an internal escalation playbook for the highest-risk accounts. This is the customer-communications program — distinct from [[feature-sunset-plan]] (the kill decision, data handling, and code removal) and [[api-versioning-strategy]] (the technical versioning mechanics)."4disable-model-invocation: true # skill-optimizer5metadata:6 source: https://skillmd.com/skills/slipcast-dev/deprecation-comms-plan7---89# Deprecation Comms Plan Skill1011Deprecations go wrong in two ways: too fast (customers get broken and churn angry) or too quiet (they find out when it breaks). This skill plans the wind-down as a *communications program*, not an announcement — enough runway, messaging matched to how much each customer depends on the thing, a real migration path, and a plan for the accounts that will need a human.1213## Working from a brief1415Given what's being deprecated and why, **produce the full plan** — infer the risk tiers from usage and contract exposure. Right-size the runway to how hard the migration is (an internal flag flip is weeks; a public API is many months). If there's no migration path yet, flag that as a blocker before any announcement.1617## Required Inputs1819Ask for (if not provided, else infer and label the assumption):20- **What's being deprecated** and **why** (cost, security, strategy, replaced-by)21- **Who depends on it** — rough usage, and which segments/contracts are exposed22- **The replacement / migration path** (or that there isn't one yet)23- **Hard constraints** — a forcing date (security, legal, contract), team capacity2425## Output Format2627### Deprecation policy in one line28The principle you're committing to (e.g. _"announce → N months deprecated (works, warns) → sunset, with a migration path live before we announce"_).2930### Timeline3132| Phase | Date / window | What changes | What customers can still do |33|---|---|---|---|34| Announce | | nothing breaks; docs + warnings | full use, start migrating |35| Deprecated | | warnings, no new adoption | migrate |36| Sunset | | turned off | must have migrated |3738Include grace periods and any extension policy for large accounts.3940### Tiered messaging41Segmented by dependence, not one blast:42- **Tier 1 — heavy/contractual users:** proactive, human (CSM/AM), often a call + tailored plan.43- **Tier 2 — active users:** direct email + in-product warning + migration guide.44- **Tier 3 — light/dormant:** changelog, docs banner, deprecation headers.4546For each: the core message (what, when, why, what to do), the ask, and the escalation path.4748### Migration guide outline49The structure of the how-to: before/after, step-by-step, code/config examples, a mapping table (old → new), FAQ, and where to get help.5051### Channel plan52Which channels fire at which phase — email, in-product, docs/changelog, API deprecation headers/`Sunset` header, status page, community/social — and the cadence (announce, reminders at intervals, final notice).5354### Internal escalation playbook55The at-risk account list, who owns each, the CSM talking points, the "customer can't migrate in time" decision tree, and the exception/extension approval path.5657## Quality Checks5859- [ ] A migration path exists and is referenced everywhere before any customer message goes out60- [ ] Runway is sized to migration difficulty, with grace periods stated61- [ ] Messaging is tiered by dependence; Tier-1 accounts get a human, not a blast62- [ ] Every message says what, when, why, and the exact next step63- [ ] The channel cadence includes reminders and a final notice, not a single announcement64- [ ] High-risk accounts have a named owner and an escalation/extension path6566## Anti-Patterns6768- Too little runway for the migration actually required69- A silent breaking change, or burying it in a changelog nobody reads70- Announcing before the migration path is live71- One-size messaging that treats a whale like a dormant free user72- No plan for the accounts that physically can't migrate in time73- "Why" that blames the customer or the old system instead of owning the change7475## Example Trigger Phrases7677- "Winding down."78- "Plan a breaking change."79- "Migrate customers off a legacy path."