Skill library

Skill library
Developerskills/developer/release-notes/SKILL.md

Release Notes

Customer-facing release notes. The core rule — if it's not written here, it wasn't delivered.

Release Notes

Release notes are a deliverable. They are not a summary of what happened — they are the canonical statement of what a customer can rely on. The rule that governs everything else is short:

If it's not written in the release note, it is considered not delivered.

A feature that ships without a release-notes entry has no observable existence for the customer, no audit trail for Compliance, and no anchor for support when a question arrives. So the release notes are written before the feature is gated for release, reviewed alongside the code, and published the moment the deploy succeeds.

What goes in

Every release produces one set of notes structured as follows:

  • Version and date. Semantic version (vMAJOR.MINOR.PATCH) and the timestamp the release was promoted to production.
  • Summary. Two sentences. Plain language. What's different now versus before.
  • New capabilities. Bullet list of user-visible additions, one line of context per bullet.
  • Behaviour changes. Anything an existing user might notice as different. Defaults, validation, rate limits, copy. Required even if the team thinks "it's not really a change."
  • Fixed issues. Bugs that affected published functionality. Reference the public incident ID if there was one.
  • Known issues. Anything we shipped with a known limitation, including a workaround when one exists.
  • Compatibility. API, integration, data format, browser breaks. Required even if the team thinks "no one was using that."

Voice and forbidden phrases

Release notes are written for a person using SPYN, not for the engineer who built the feature. Use second person — "you can now…" — and active voice. Mention the screen, button, or flow the customer actually sees.

Forbidden vague phrases — these will be rejected at review:

  • "UI fixes"
  • "Improvements"
  • "Various bug fixes"
  • "Performance enhancements"
  • "Under-the-hood changes"
  • "Tweaks"
  • "Polish"

If a change deserves a release-notes entry, it deserves a specific description. If it doesn't deserve a specific description, it doesn't go in the release notes — and by the rule above, it isn't delivered.

Regulatory annexes

For customers under regulatory regimes the release notes carry additional structured annexes:

  • EU MDR. Class IIa+ releases include a risk-management summary referencing the updated risk file plus the Person Responsible for Regulatory Compliance and sign-off date.
  • ISO 27001. Releases changing security controls reference the updated Statement of Applicability entry and link to the change advisory board minutes.
  • SOC 2. Releases changing controls in scope of the latest audit reference the control owner and identifier.

Annexes are generated from structured metadata in the release manifest; release engineers do not write them by hand.

Approval before publication

Compliance reviews release notes before deploy. Approval criteria: completeness against the structure above, accurate categorization of behaviour changes, presence of regulatory annexes where required, no forbidden phrases. A release cannot promote to production with unapproved notes — enforced at the deploy gate.

Owned by

Engineering Leadership, with Compliance as co-owner for the regulatory annexes. Audited by the Master skill on a 60-day cadence.