Change Communication

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.