/change-communication

name: change-communication
description: "Produce a communication package for a design system change — release notes, migration guide, and team announcement. This produces communication artefacts for changes that have already been decided, NOT the deprecation lifecycle itself. Trigger when someone says: communicate this change, breaking change announcement, how do I tell teams about this, release notes, change log, write the announcement, or anything about communicating an update, release, or breaking change to consuming teams. Do NOT trigger for planning or executing a deprecation — use deprecation-process for that, which includes its own communication plan as part of the full lifecycle."

Change communication

A skill for producing a complete change communication package: release notes, migration guidance where needed, and a team announcement ready to send. Calibrated to the change type so a patch note does not read like a major incident, and a breaking change does not get buried in a routine release update.

Context

Change communication is the part of design system work that feels like overhead until it is done badly. A breaking change that arrives without notice destroys trust faster than any number of missing components. A routine release that goes out without clear notes creates a support burden for the design systems team.

The goal is communication proportional to impact. This skill distinguishes between change types and produces output calibrated accordingly — a minor enhancement gets release notes and nothing more, while a breaking change gets a full package including migration guidance and a direct team notification.

Boundaries

This skill communicates changes that have already been decided. It does not decide what to change, plan a deprecation lifecycle, or execute a migration — use `deprecation-process` for deprecation planning and `codemod-generator` for migration execution. If the change has not been finalised, ask the user to confirm the change details before producing communication. If the change affects no consuming teams (internal refactor with no API surface change), a communication package is unnecessary — confirm with the user and stop.

---

Step 1: Classify the change

Ask for or confirm:

• What changed? (component, token, pattern, API, tooling, governance)
• Is it breaking? (Does it require consuming teams to change their code or designs to avoid regressions?)
• What is the scope of impact? (How many teams or products are affected?)
• Is there a migration path?

**Small-system note (fewer than 5 components):** For systems this size, calibrate communication intensity down. The audience is smaller and likely in closer contact — a breaking change to one of four components affects the entire consumer base, but that base may be a single team who you can notify directly in a standup or sync. Release notes are still required (they are the historical record), but the "announcement" may be a Slack message rather than a formal communication package. If the change is significant, a direct conversation replaces the written migration guide — walk through it together.

Classification:

**Patch** — bug fix, documentation correction, minor visual refinement with no API changes. No consuming team action required.

**Minor enhancement** — new prop, new variant, new component, new token. Backward compatible. Consuming teams can adopt at their own pace.

**Breaking change** — removed prop, renamed token, changed component API in a way that breaks existing usage, changed token values in a way that affects visual output. Consuming teams must act.

**System-level change** — governance policy, naming convention, architecture decision, tooling change. Wide blast radius, may not be technically breaking but affects how teams work with the system.

Step 1b: Communication tailoring matrix

Before producing the communication package, assess the adoption context. The same change needs different messaging depending on how teams are engaging with the system.

**High-adoption teams** (actively using, contributing, engaged):

• Communication tone: informational. These teams will read release notes proactively.
• Migration support: self-service. Provide the migration guide and let them execute.
• Channel: standard channels (release notes, Slack announcement).

**Partial-adoption teams** (using some components, not fully engaged):

• Communication tone: supportive. Frame the change as an improvement to something they already use.
• Migration support: offer a pairing session or office hours slot.
• Channel: direct notification in addition to standard channels.

**Low-adoption or at-risk teams** (not using the system, or usage is declining):

• Communication tone: minimal. Do not over-communicate changes to teams that are not yet engaged — it creates noise.
• Migration support: N/A unless the change affects the few components they do use.
• Channel: only notify if they are directly affected.

**New teams** (recently onboarded or in onboarding):

• Communication tone: contextual. Frame the change within their onboarding experience.
• Migration support: proactive. Ensure their onboarding materials reflect the change.
• Channel: direct, through their onboarding contact.

This matrix prevents the common failure mode of communicating every change at the same intensity to every team, which trains teams to ignore system communications.

Step 2: Produce the communication package

---

For a patch:

**Release notes entry only**

Format:

[Component or token name] — [one-sentence description of the fix]
Affected: [who is affected, if anyone]
Action required: None

No announcement needed. Patch notes accumulate in the release log and are reviewed at the team's convenience.

---

For a minor enhancement:

**Release notes entry + brief announcement**

**Release notes entry:**

[Component or token name] — [what was added]
What's new: [one to two sentences describing the addit