---
name: change-communication
description: "Write release notes, a migration guide and a team announcement for a design system change that is already decided, scaled to its impact. Triggers: release notes, announce this change, tell teams about a breaking change. Semver call: version-bump-advisor. Deprecation plan: deprecation-process."
allowed-tools: Read, Write, Grep, Glob, Bash(cat:*), Bash(ls:*), Bash(git log:*), Bash(git tag:*)
references:
  - ../../knowledge-notes/output-discipline.md
---

# Change communication

A skill for producing a complete change communication package: release notes, migration guidance where needed, and a team announcement with every open gap listed at the top. 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.

## Before you begin: verify references

Confirm that every path in this skill's frontmatter `references:` exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example `npx skills install`) dropped the repo-root `knowledge-notes/` directory. Tell the user to reinstall by a method in `1-INSTALL.md` and run `verify-install.sh` from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.

## 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. It is, however, the single owner of the migration guide: `deprecation-process` hands it a mapping table and `version-bump-advisor` a list of breaking changes with before/after rows, and this skill renders the guide once so the announcement, the release notes and the docs all say the same thing. 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

Read before asking: `CHANGELOG.md` and `git log <last tag>..HEAD` for the actual change list; `.changeset/` for pending changesets and their summaries; `.ds-ops-config.yml` for `system.name` and `integrations.npm.package_name`, which the notes and announcement name. A package's own change list is the source; the user's description of it fills gaps.

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: take the patch / minor / major call from `version-bump-advisor` output or the user. If neither exists and the change touches a published API or token, run `version-bump-advisor` first rather than classifying here. Map the result to a communication tier:

- **Patch** → release notes entry only
- **Minor** → release notes + brief announcement
- **Major (breaking)** → full package: release notes, migration guide, direct notification
- **System-level change** (governance, naming convention, architecture, tooling; may not have a semver bump) → announcement, context document, Q&A period

## Step 1b: Communication tailoring matrix (only with adoption data)

Use this matrix only when `adoption-report` output or the user tells you how each team engages with the system. Without that, skip it and send the same package to every affected team; don't guess a team's adoption level.

**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 change:

**Release notes entry + brief announcement**

**Release notes entry:**
```
[Component, token or feature] — [what was added or changed]
What's new: [one to two sentences describing the addition or change and its purpose]
How to use it: [one sentence or a link to the documentation]
Action required: None — existing usage is unaffected
```

**Announcement (Slack or equivalent):**
Keep to three to four sentences. What was added, why it exists, where to find it. No preamble.

Template:
> [Component/token name] is now in the system. [One sentence on what it does.] [One sentence on when to use it.] Documentation is at [link].

---

### For a breaking change:

**Full package: release notes + migration guide + direct notification**

**Release notes entry:**
```
[Component or token name] — BREAKING CHANGE
What changed: [specific description of what changed]
Why it changed: [one sentence — reason, not justification]
Affected: [who is affected]
Migration: See migration guide below
Action required by: [date]
```

**Migration guide:**

The migration guide should be specific enough to follow without additional context. Include:

1. What the old behaviour was
2. What the new behaviour is
3. Step-by-step migration instructions with before/after examples where useful

```
Before:
<Button variant="danger" />

After:
<Button variant="destructive" />
```

4. Any edge cases that require special handling
5. What to do if migration is not feasible by the deadline (contact route, escalation path)

If a migration script exists or can be provided, include it or link to it here.

**Direct notification:**

Breaking changes do not wait to be discovered in release notes. Send a direct notification to all affected teams through their primary communication channel.

Template:
> **[System name] breaking change — action required by [date]**
>
> [What changed, in one sentence.]
>
> If you use [component/token name], you will need to [specific action] before [date] to avoid [specific consequence].
>
> Migration guide: [link]
> Questions: [channel or contact]

The notification should be short enough to read in thirty seconds and specific enough that someone reading it immediately knows whether they are affected.

---

### For a system-level change:

**Full package: announcement + context document + Q&A period**

System-level changes need more than release notes. They need context. Why is this changing? What does it mean for teams day-to-day? What happens to work that was done under the old system?

**Announcement:**
Lead with the change and its impact, not the reasoning. Teams want to know what they need to do before they want to understand why.

> **[What is changing] — effective [date]**
>
> [One sentence on what this means for teams using the system.]
>
> [Two to three sentences on what teams need to know: what changes in their workflow, what does not change, and what support is available.]
>
> Full context and rationale: [link to context document]
> Q&A session: [date/time or async channel]

**Context document:**
A separate document covering:
- What prompted the change
- What was considered and why this direction was chosen (reference the decision record if one exists)
- What the transition looks like — timeline, what is changing when
- What stays the same
- Known concerns and how they were addressed

**Q&A period:**
For significant system-level changes, offer a defined period for questions — either a live session or a dedicated async channel with a named response time. Close the loop after: summarise the key questions raised and the answers given, and add that summary to the context document.

---

### The design side

Half of a design system's consumers never read a changelog: they open Figma. For any change that touches the Figma library, the package includes:

- **Library publish notes:** the description entered when the library is published, in the same shape as the release notes entry (what changed, the replacement, the date, the link to the guide). Designers see this in the library update prompt, which is the only announcement many of them get
- **In-library signals:** for a deprecation or rename, the component or variable renamed with a `[Deprecated]` prefix or moved to a Deprecated page, with its description pointing at the replacement; new components placed and named where designers will find them
- **The designers' channel:** the announcement posted where designers are, not only where engineers are, with the Figma-side action stated ("update the library; `OldCard` is now under Deprecated")

Write these alongside the code-side notes; a change communicated only to engineers shows up as design-to-code drift a sprint later.

## Step 3: Choose the channels

Different communication channels serve different purposes. Calibrate by change type:

| Channel | When to use |
|---|---|
| Release notes / changelog | Every change, every time |
| Figma library publish notes | Every change that touches the library |
| Slack / team channels (engineers and designers) | Minor changes and above |
| Direct team notification | Breaking changes and system-level changes |
| Email | Breaking changes with external or cross-org impact |
| Meeting / live session | System-level changes with significant workflow impact |


## Step 4: Set a follow-up

For breaking changes and system-level changes, schedule a follow-up:
- One week before the action-required date: reminder to teams who have not yet migrated
- On the action-required date: confirmation that the change is live, any last-minute support available
- Two weeks after: review whether migration is complete, identify any teams who need additional help

Document this follow-up schedule alongside the communication so it does not get missed.

## Quality checks

- Change classification comes from `version-bump-advisor` or the user — breaking changes are not communicated as minor enhancements
- Migration guide is specific enough to follow without additional context
- Direct notification for breaking changes names the specific consequence of inaction
- Channels are appropriate to the change type, and any change that touches the Figma library has publish notes and a designers' announcement
- The change list came from the CHANGELOG, git history or changesets where a repository was in reach
- A follow-up schedule exists for breaking and system-level changes
- Fill what's known; list every unresolved placeholder (dates, links, owners, contacts) at the top for the user. Never invent dates, links, owners, rationale or percentages