Reference — generated from the toolkit

Source of truth: toolkit/skills/release-notes/spec.md. Edit it there; this page is regenerated on build.

Skill: release-notes

• Owner: AI + Product
• Version: 0.1.0
• Lifecycle: draft
• Phase: production

Trigger

Every release. The release-comms standard requires audience-split notes, and at weekly cadence hand-writing three views per release is the bottleneck that quietly slows shipping. Generate from the merge history so a human approves rather than authors.

Inputs → outputs

• Inputs: the commits and PR titles/descriptions between the previous release tag and this one (Conventional Commits per the branching & commit conventions), and the audience formats from the release-comms standard.
• Outputs: three drafts for the one release — client (what's new and what it means for them, plain language), support (operational changes, what to watch, runbook deltas), internal (the technical detail) — plus the Keep a Changelog entry. Breaking changes flagged at the top of all three views.

Procedure

1. Collect commits and PRs between tags; group by Conventional Commit type and scope.
2. Classify each change per audience: client-visible / support-relevant / internal-only. When unsure, keep it out of the client view and in internal — never guess client impact.
3. Draft the three views. Every line traces to a commit or PR. A change the skill can't confidently describe is listed with its PR link and marked "needs a human sentence" — never paraphrased into something plausible.
4. Flag anything breaking — feat!/BREAKING CHANGE markers, a SemVer major, or an API/contract change — prominently in all three views. Breaking-change wording is always human-reviewed before it goes anywhere.
5. Emit for approval per the release-comms standard; the approved notes join the release evidence pack at Production Readiness.

Guardrails & permissions

• Read-only on repo history; produces drafts only — publishing or sending notes to clients is a human action.
• Never invents changes: no line without a traceable source commit/PR; no forward-looking, roadmap or promotional language.
• Client-facing wording for regulated functionality (e.g. MTA processing, claims handling, anything with FCA-sensitive framing) is drafted but held for compliance-aware review — the skill flags these lines, it does not soften them.

Failure modes

• Marketing drift — client notes overstating what shipped (mitigated: traceability rule; human approval on every view).
• Missed breaking change — a breaking change the commits didn't mark (mitigated: SemVer check and API/contract diff where tooling exists; commit linting upstream keeps markers honest).
• Garbage in — non-conforming commit messages yield thin notes (mitigated: commit linting at the merge gate; non-conforming changes are listed raw for a human to word, not silently dropped).

Golden scenarios

Scenario	Input	Expected output	Pass criterion
Clean release	fixture history of conventional commits	three views covering all client-visible changes	every line traces to a commit/PR
Breaking change	fixture with a feat! commit	flagged at the top of all three views	breaking change never unflagged
Invention check	fixture history	no content beyond the source changes	zero untraceable lines
Messy history	non-conforming commit messages	listed raw for human wording	no invented descriptions