/change-communication

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