Sunset Deprecation Communicator

---
name: sunset-deprecation-communicator
description: Plan and draft the sunset or deprecation of a PRODUCT feature or public API for USERS and integrators — establish the already-made decision's rationale, assess impact, define the migration path, set a deprecation window and firm sunset date, and prepare an escalating multi-channel communication plan plus grandfathering and support. Planning only; sending customer messages or changing live headers needs its own authorization. This is NOT retirement of a library SKILL (skill-deprecation-planner). Use when planning a feature or API sunset and its customer announcement. Do NOT use to retire a library skill or set the standing API deprecation POLICY (api-event-architect).
---

# Sunset & Deprecation Communicator

**Terms:** API means application programming interface. This skill drafts
the plan and messages; actual customer outreach or live header changes
follow their own applicable authorization.

## Purpose

Killing a feature is easy; killing it without burning the users who
depend on it is the actual work. The failure modes are familiar: a
silent removal that greets integrators with a 404 (not found) error on Monday morning, a
"deprecated" banner nobody reads followed by a sunset with no migration
path, or a public API version pulled on a date that was mentioned once in
a changelog. This skill plans the humane sunset: the rationale users will
be told, an honest impact assessment of who breaks and how badly, a
concrete migration path to the replacement, a timeline with a real
deprecation window and a firm date, and a multi-channel, escalating
communication plan that reaches people before it's too late — plus
grandfathering and support for the hardest-hit. Its center of gravity is
COMMUNICATION and MIGRATION for external users. It is deliberately not
`skill-deprecation-planner`, which retires an internal library skill.

## Use When

- Use when: sunsetting or deprecating a product FEATURE and its users
  need a migration path and warning.
- Use when: deprecating a public API version, endpoint, or field that
  integrators depend on, with a compatibility/sunset window.
- Use when: planning an end-of-life announcement and you need the
  timeline, channels, and messaging drafted.
- Use when: a heavy-usage or contractual customer needs grandfathering,
  exceptions, or extended-support handling during a sunset.
- Do NOT use when: the thing being retired is a SKILL in this library —
  the mark→redirect→remove lifecycle, the reverse-link sweep across
  neighbor descriptions/trigger-evals, and the catalog/README rows are
  `skill-deprecation-planner`. Different object (a library skill, not a
  product feature), different work (registration mechanics, not user
  comms).
- Do NOT use when: the task is the STANDING deprecation POLICY — how long
  API versions are supported by default, sunset-header conventions,
  versioning rules — that is `api-event-architect`; this skill executes a
  specific sunset within that policy.
- Do NOT use when: the task is building the notification delivery SYSTEM
  (preference center, channels, in-app notification center) — that is
  `notification-webhook-ux-designer`; this skill plans the sunset MESSAGING
  that rides on it.

## Inputs to Inspect

1. The decision and its rationale: what is being sunset and WHY (low
   usage, replaced, cost, security, strategy) — confirmed as decided;
   this skill communicates it, it does not make the call.
2. The dependency map: who uses the feature/endpoint — segments,
   integrators, volume, revenue, and any contractual commitments naming
   it.
3. The replacement: the alternative users should move to, whether it's at
   parity, and how hard the migration is (from `api-event-architect` /
   `schema-evolution-planner` outputs where relevant).
4. The standing deprecation policy: default support windows, sunset-header
   conventions, and changelog practices this sunset must follow
   (`api-event-architect`).
5. The available communication channels and their reach:
   announcement/blog, in-app, docs, email, and (for APIs) response
   headers — the delivery system owned by `notification-webhook-ux-designer`.

## Workflow

1. **Anchor the rationale and confirm it's decided.** Capture WHY in
   terms users will accept. If the sunset itself is still in question,
   stop — deciding it is a product call, not this skill's; this skill
   plans the communication of a made decision.
2. **Assess impact honestly.** Who depends on it, how many, how heavily,
   and what breaks for them. Identify the hardest-hit (deep integrations,
   contractual users) — they drive the window length and the outreach
   plan. No replacement at parity is itself a finding to surface, not
   hide.
3. **Define the migration path.** The concrete alternative and a
   migration guide with effort estimate; automated migration or tooling
   where feasible. If there is genuinely no replacement, say so plainly
   and give users the honest options.
4. **Set the timeline.** Announcement → deprecation period (still works,
   discouraged, warnings emitted) → firm sunset date (removed). Length
   proportional to impact and migration effort, and at least the standing
   policy's minimum. Dates are firm and stated once, everywhere the same.
5. **Build the escalating communication plan.** Multi-channel and
   repeated, not a single post: initial announcement (changelog/blog/
   email), in-app notices, docs marked deprecated with the migration
   link, reminder emails escalating as the date nears, and targeted
   outreach to heavy/contractual users. For APIs: `Deprecation`/`Sunset`
   response headers, versioned docs, and changelog entries. Each message
   says what, why, when, what to do, and where to get help.
6. **Plan grandfathering, exceptions, and support.** Who (if anyone) gets
   an extension or extended support, the escalation path for stuck users,
   and readiness of support/success teams for the transition wave. When who
   gets an exception is the owner's call (hardest-hit users cannot migrate
   within the window), teach it before asking. Define *grandfathering*
   (named customers keep the old behavior past the sunset date for a stated
   term), *extended support* (the old surface keeps working and gets fixes
   under a separate term or fee), and the *sunset date* in plain language.
   Compare no exceptions, a time-boxed extension for named accounts, and an
   extended-support tier: why each fits, its pros and cons, and its money
   (revenue kept or lost, cost of running the old surface), setup, and
   upkeep cost, or unknown. Recommend one, say why and what fact would change
   it, then ask exactly one owner question. The public sunset date stays
   firm; the window meets at least the standing policy's minimum (owned by
   `api-event-architect`). Grandfathered or extended-support accounts are
   served the old surface through a named allowlist; the public tombstone
   applies to everyone else. The answer shapes the plan; it does not authorize
   customer outreach or live header changes, any new contractual or paid
   extended-support term needs the commercial owner's approval, and a
   contractual commitment still follows Stop Conditions.
7. **Design the post-sunset behavior.** For all non-exempt traffic, the
   removal and a clear tombstone — an explanatory error/redirect pointing
   to the replacement, never a silent 404 — plus monitoring for stragglers
   still calling the dead surface. When an exception is chosen, accounts on
   the named grandfathering or extended-support allowlist (step 6) keep the
   old surface until their stated expiry, then get the same tombstone; hard
   removal of the old surface waits for the last expiry, and the public
   sunset date does not move.
8. **Name boundaries and deliver.** Standing policy/versioning →
   `api-event-architect`; the notification delivery system →
   `notification-webhook-ux-designer`; a LIBRARY skill's retirement →
   `skill-deprecation-planner`. Produce the sunset plan in the Output
   Format.

The impact-assessment checklist, window-length guidance, the escalating-
comms schedule, and API deprecation-header conventions:
[references/sunset-comms-sheet.md](references/sunset-comms-sheet.md).

## Output Format

```
SUNSET PLAN — <feature / API surface>
Rationale:     <why, in user-acceptable terms; confirmed decided>
Impact:        <who depends, volume, revenue, contractual; hardest-hit named>
Migration:     <replacement + guide + effort; tooling; "no parity" stated if true>
Timeline:      announce <date> → deprecation window <len> → SUNSET <firm date>
Comms plan:    channels × schedule (announcement, in-app, docs, escalating email,
               targeted outreach; API: Deprecation/Sunset headers + changelog)
Message content: what / why / when / what-to-do / where-to-get-help
Grandfathering: exceptions, extended support, escalation path; if an exception is
               chosen: allowlist = <named account → expiry date>, each term stated
Exception choice: plain terms; none / time-boxed extension / extended-support tier — why,
               pros/cons, money/setup/upkeep or unknown; recommendation + what would
               change it; ONE owner question; authorizes no outreach
Post-sunset:   non-allowlisted traffic → tombstone (explanatory error/redirect →
               replacement, NOT silent 404); allowlisted accounts keep the old surface
               until their expiry, then tombstone; hard removal after the last expiry;
               straggler monitoring
Boundaries:    policy/versioning → api-event-architect; delivery system →
               notification-webhook-ux-designer; SKILL retirement → skill-deprecation-planner
```

## Validation Checklist

- [ ] The rationale is captured and the decision confirmed made — this
      skill communicates, it doesn't decide the sunset.
- [ ] Impact names who breaks, how badly, and the hardest-hit
      (contractual/deep-integration) users.
- [ ] A concrete migration path exists, or the lack of a parity
      replacement is stated plainly.
- [ ] The timeline has a real deprecation window and a firm sunset date
      meeting at least the standing policy minimum.
- [ ] Communication is multi-channel and ESCALATING, not a single notice;
      each message covers what/why/when/what-to-do/help.
- [ ] Grandfathering/exceptions and a support/escalation path are defined.
- [ ] An owner exception choice has terms defined; each option's why,
      pros/cons and cost-or-unknown; a recommendation plus what would change
      it; one owner question; the answer grants no authority.
- [ ] Post-sunset leaves an explanatory tombstone, not a silent 404, and
      monitors stragglers.
- [ ] When an exception is chosen, the plan names each allowlisted account
      and its expiry, and post-sunset routing keeps those accounts on the
      old surface until then, tombstoning only non-exempt traffic.
- [ ] Standing policy, the delivery system, and library-skill retirement
      are handed to their owning skills.

## Gotchas

- A deprecation banner is not a communication plan. People don't read
  banners; they hit the wall on sunset day. Escalating, multi-channel,
  and targeted-to-heavy-users is what actually reaches them.
- Sunsetting without a migration path is an eviction. If there's no
  replacement at parity, that's a decision to reconsider or to state
  honestly — not something to paper over with a cheerful announcement.
- A silent 404 on sunset day tells the integrator nothing; a tombstone
  that says "this was retired on X, use Y" turns a mystery outage into a
  guided migration. Design the after-state.
- Moving the sunset date because users weren't ready teaches everyone the
  date is negotiable, and the next deprecation is ignored. Set a window
  long enough to be firm, then hold it (with grandfathering as the
  pressure valve, not date-slipping).
- The heaviest users are the quietest until it breaks — they've automated
  around your feature. Targeted outreach to top consumers beats hoping
  they saw the blog post.
- This is not retiring a library skill. If the object is a skill in
  `.claude/skills/` with neighbor trigger-evals and catalog rows, the
  reverse-link sweep and mark→redirect→remove lifecycle are
  `skill-deprecation-planner`'s — a completely different mechanism.

## Stop Conditions

- The object being retired is a LIBRARY SKILL (its lifecycle, reverse-
  link sweep, catalog/README rows) → route to `skill-deprecation-planner`;
  this skill handles product features and APIs for external users.
- The sunset itself is not actually decided (still debating whether to
  kill it) → stop; the decision is a product/business call. This skill
  communicates a made decision, it doesn't make it.
- There is no replacement at parity and users have no viable path off the
  feature → surface this to a human as a reason to reconsider the sunset
  or its timing, not to communicate around.
- A contractual commitment names the feature/endpoint being sunset →
  halt and route to the commitment owner; sunsetting contracted
  functionality is a legal/commercial decision, not a comms plan.

## Supporting Files

- [references/sunset-comms-sheet.md](references/sunset-comms-sheet.md) —
  the impact-assessment checklist, window-length guidance by impact, the
  escalating-communication schedule, and API `Deprecation`/`Sunset`
  header conventions.
- `evals/evals.json` — behavior cases including the API-version sunset,
  the no-migration-path refusal, and the escalating-comms plan.
- `evals/trigger-evals.json` — discrimination against `skill-deprecation-planner`
  (THE seam: product feature vs library skill), `api-event-architect`
  (standing policy), and `notification-webhook-ux-designer` (delivery system).