sunset-deprecation-communicator

name

sunset-deprecation-communicator

description

Plan and communicate the sunset or deprecation of a PRODUCT feature or public API to the USERS and integrators who depend on it — establish the (already-made) decision's rationale, assess impact (who uses it, what breaks), define the migration path to the replacement, set a timeline with a deprecation window and a firm sunset date, and build the multi-channel escalating communication plan (announcement, in-app, docs, reminder emails; for APIs deprecation/sunset headers + changelog), plus grandfathering and transition support. The center of gravity is USER communication and migration. This is NOT the retirement of a library SKILL (mark→redirect→remove, reverse-link sweep, catalog rows) — that is skill-deprecation-planner. Use when sunsetting a feature, deprecating an API version/endpoint, or announcing an end-of-life to customers. Do NOT use to retire a skill in THIS library (skill-deprecation-planner) or set the standing API deprecation POLICY (api-event-architect).

Sunset & Deprecation Communicator

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 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: announcing an end-of-life to customers and you need the timeline, channels, and messaging planned.
• 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.
7. Design the post-sunset behavior. 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.
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.

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
Post-sunset:   tombstone (explanatory error/redirect → replacement, NOT silent 404);
               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.
• Post-sunset leaves an explanatory tombstone, not a silent 404, and monitors stragglers.
• 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 — 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).