write-release-notes
Author customer-facing release notes — headline, user-benefit framing, breaking changes called out, no internal-jargon component names.
- License 许可
- MIT
- 最近更新
- 2026-10-29
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- write-release-notes
- description
- Author customer-facing release notes — headline, user-benefit framing, breaking changes called out, no internal-jargon component names.
03 SKILL.md 正文
write-release-notes
Customer-facing release notes. Different from CHANGELOG: the audience is users, not engineers. Tone is announcement + benefit, not changelog rollup.
Mode: analytical — judgment inside a fixed frame. Keep the output shape; every verdict cites its evidence; unknowns are marked [TBD] or [VERIFY], never filled in.
When to use
- A release is being prepared and you want notes the customer-facing site / email blast can use.
- The internal CHANGELOG exists; this skill repackages it for users.
Related skills
polymath-release:release-notes— engineer-facing release notes drafted directly fromCHANGELOG.md[Unreleased]. Run that first for the version-bump notes; this skill repackages them for customers (announcement + benefit framing, no internal-jargon component names).polymath-release:changelog— append the canonical[Unreleased]entry that both this skill andpolymath-release:release-notesconsume.
Inputs
- The version being released + date.
- The CHANGELOG entries since the last release (or
git log --oneline). - Optional: any customer-reported issues that this release fixes (call out individually).
Procedure
- Headline: one sentence on the most important change. Lead with the benefit, not the mechanism.
- What's new: each
Addedfrom the CHANGELOG, restated in customer language. Skip internal-only changes. - Notable changes:
Changed,Fixed,Security,Deprecated,Removedthat customers will notice. - Breaking changes: own section. Migration path required for each. If anyone has to change anything in their code or workflow, this section is mandatory.
- Known issues: shipping ≠ no-bugs. Be honest about what's pending.
- Security fixes: credit the reporter when they consented; cite the advisory ID.
- Claims trace to sources. A speedup, a fixed bug, or a number must come from the CHANGELOG, a PR, or a measurement — every figure traces to the source material; a missing one is written
[TBD: <what>]and listed in the summary.
Style
- Active voice ("We added X" or "X now does Y").
- User benefit, not implementation ("Faster check-outs" beats "Optimized the cart query").
- No internal component names ("the checkout API" not "v2-cart-svc").
- No emojis.
Output
Release notes — Polymath v1.4.0 (2026-05-24)
Headline:
Refunds now complete in under a second — a 4× speedup for high-volume merchants.
What's new
- Refund creation is now sub-second at P95 across all regions.
- You can now view refund status in the timeline view of an order.
Notable changes
- Idempotency-Key is now required on refund creation (previously optional).
See the migration note below.
Breaking changes
- `POST /v1/refunds` now requires an `Idempotency-Key` header on every
request. Calls without it return 400.
Migration: include a UUID `Idempotency-Key` per refund attempt.
Security fixes
- SEC-2026-0042 (Medium): IDOR on /v1/orders/{id}/refunds — fixed in 1.4.0.
Reported by <name>. See advisory link.
Known issues
- The new timeline view doesn't yet render correctly on Safari 15. Tracked in #1234.
Quality bar
- Headline names benefit, not mechanism.
- Breaking changes have a Migration line each.
- Internal jargon scrubbed; if the customer wouldn't recognize a component name, replace it.
- Active voice.
- Security fixes credit reporters who consented.
Anti-patterns to avoid
- Pasting the CHANGELOG without rewriting for customer audience.
- "Performance improvements" without a number.
- Burying breaking changes in the middle of "Notable changes".
- Marketing puffery ("We're excited to announce …"). Just say what changed.
04 同仓库更多 Skills
runbook
Write or refresh an operational runbook for an alert/symptom; structured as TL;DR + Pre-checks + Steps + Verification + Rollback + Escalation.
rfc
Draft a lightweight design RFC to docs/rfcs/<slug>.md; Summary, Motivation, Detailed design, Drawbacks, Alternatives, Unresolved questions. A proposal to debate, not a recorded decision (adr).
editorial-pass
Review and tighten prose in a Markdown artifact for a target tone (terse, formal, friendly) without dropping information; preserve quotations and load-bearing constraints.
architecture-review-facilitation
Run an architecture review as a process — entry criteria, reviewer checklist, decision log, and follow-up actions — pairing the design artifact with a red-team pass.
architecture-doc
Write a C4-style architecture document; System Context + Containers (+ Components when interesting) with mermaid diagrams. Describes structure, not a decision (adr) or proposal (rfc).
adr
Write an Architecture Decision Record (Michael Nygard format) to docs/adrs/NNNN-<slug>.md; frontmatter validated by the ADR artifact schema. Records a made decision, not a proposal to debate (rfc).