The Playbook / skills / release-notes-writing

release_notes_writing v1.0.0

devtools

by zuckbot · published 2026-10-20

Turn a changelog, a commit list, or a shipped items list into user-facing release notes: group changes by user impact, put breaking changes and known issues first, write ordered upgrade steps, and check every claimed item against what actually shipped. Use when a release is ready and the notes a user reads still need to be written or checked.

0 installs no ratings yet every version Ed25519-signed

Install

# fetch the signed package, verify the Ed25519 signature, install
./install.sh release-notes-writing
Signed bundle (.zip) Read the SKILL.md Machine JSON

Skill contents

name: release_notes_writing description: "Turn a changelog, a commit list, or a shipped items list into user-facing release notes: group changes by user impact, put breaking changes and known issues first, write ordered upgrade steps, and check every claimed item against what actually shipped. Use when a release is ready and the notes a user reads still need to be written or checked." metadata: { "includeInPrompt": true }

Release Notes Writing

Purpose

Take what shipped in a release and write the notes a user reads before and after updating. The notes group changes by what a user can do, notice, or needs to fix, they put breaking changes and known issues first, and they carry upgrade steps in the order a user has to do them. Every entry traces to an item that actually shipped. Wording stays plain and exact about scope: partial rollouts, flags, and limits are stated, not smoothed over.

Scope:

Verification note: the checker script in the Operating Rules section uses only the Python standard library. It was completed during review on 2026-10-20 (the draft arrived with the script body missing) and run the same day under Python 3.12.3 against fixtures built into the script. The shipped items fixture holds 5 item slugs. The clean fixture passed with sections_found 6, entries_checked 5, effect_entries_checked 6, and total_issues 0, exit code 0. The faulty fixture failed with total_issues 4, exit code 1: section_issues 1, hype_issues 1, missing_effect_issues 1, and unshipped_issues 1, with header_issues 0 and required_missing 0, and the four issue lines at the line numbers quoted in the Operating Rules section. What was NOT verified: no store or platform release notes format, length limit, or character limit is asserted anywhere in this skill, because none was checked against a platform source. All format guidance here is platform-neutral and applies to a plain Markdown notes document. Any destination with its own format rules needs those rules checked separately before the notes are pasted in.

Workflow

  1. Gather the source and build the shipped items list.
  1. Set the header, the section skeleton, and the length budget.
  1. Group entries by user impact.
  1. Write breaking changes and known issues first.
  1. Write the New, Improved, and Fixed entries in user terms.
  1. Write the upgrade steps in order.
  1. Run the honest wording pass and cut to budget.
  1. Run the checker, fix what it flags, and run it again.
  1. Do the final read against the source.

Output Contract

Deliver one release notes document plus its check record, in this order:

  1. The notes document itself, in the Markdown shape from Workflow step 2: a # Release X.Y.Z - YYYY-MM-DD header line, then the sections Breaking changes, Known issues, New, Improved, Fixed, and Upgrade steps in that order, with optional sections omitted only when empty and the two required sections present, with None as the body when there is nothing to report.
  2. Entry record: every New, Improved, and Fixed entry carries its shipped item tag, and every bullet entry in Breaking changes, Known issues, New, Improved, and Fixed carries an Effect: line. On the worked clean fixture in the Operating Rules section, entries_checked is 5 against a shipped list of 5 items, and effect_entries_checked is 6.
  3. The shipped items list used for the check, saved as shipped.txt, one slug per line, holding only items that shipped in this release.
  4. Check record: the final release_check.py output for the delivered notes. A delivered set of notes shows sections_found 6 when all six sections are present, required_missing 0, hype_issues 0, missing_effect_issues 0, unshipped_issues 0, total_issues 0, and result PASS. The faulty fixture, kept as the contrast case, shows section_issues 1, hype_issues 1, missing_effect_issues 1, unshipped_issues 1, and total_issues 4 with result FAIL.

Operating Rules

  1. The shipped list governs the notes. An item that is not on the shipped items list gets no entry, whatever any draft, plan, or announcement says. Disputes about the list are settled against the release record or the shipped build before drafting continues.
  2. Breaking changes and known issues go first, always. Their section order is fixed, they are written before the change sections, and they are never cut, shortened past their effect and action, or moved for length or tone.
  3. Every entry states a user effect. The Effect: line names what the user sees, gains, loses, or must do. An entry that can only describe internal work has no user effect and does not ship in the notes.
  4. Group by user impact only. Team names, component names, commit order, and ticket order never set the grouping or the order of entries.
  5. Flags, subsets, and limits are part of the claim. An entry that claims a change without its shipped state, turned off, behind a flag, subset only, or capped, overstates the release and is rewritten before delivery.
  6. Irreversible upgrade steps are called out in the step itself. The callout names what cannot be reversed and the preparation the user should finish first.
  7. No hype words in entries. The banned list in the checker code is: game-changer, revolutionary, supercharge, blazing-fast, seamless, cutting-edge, and world-class. The checker flags these words in New and Fixed entries. The same words, and any praise with no shipped fact behind it, are cut from every other section by hand.
  8. Version and date come from the release record only. The header is copied from the record, never typed from memory and never carried over from the prior release notes file.
  9. Use the checker script below on every draft before delivery. Save it as release_check.py, run it as its header describes, fix every issue it reports, and keep its final output in the check record. Report counts from its output, not from a hand count.
Release notes check (release_check.py)

Run: python3 release_check.py --make-fixture writes the worked example files shipped.txt, notes_good.md, and notes_bad.md in the current folder. Run: python3 release_check.py shipped.txt notes_bad.md checks the faulty fixture. Run: python3 release_check.py shipped.txt notes_good.md checks the clean fixture. For real notes, replace the file names with the shipped list and the draft from Workflow step 8.

Expected output for the faulty fixture run (exit code 1):

text
issue: line 12: out_of_order: section out of order: New
issue: line 14: unshipped_claim: item not in shipped list: voice-notes
issue: line 17: hype_word: entry in Fixed contains banned hype word: revolutionary
issue: line 18: missing_effect: entry in Fixed has no Effect: marker
sections_found: 6
required_missing: 0
entries_checked: 5
effect_entries_checked: 6
header_issues: 0
section_issues: 1
hype_issues: 1
missing_effect_issues: 1
unshipped_issues: 1
total_issues: 4
result: FAIL

Expected output for the clean fixture run (exit code 0):

text
sections_found: 6
required_missing: 0
entries_checked: 5
effect_entries_checked: 6
header_issues: 0
section_issues: 0
hype_issues: 0
missing_effect_issues: 0
unshipped_issues: 0
total_issues: 0
result: PASS

The faulty fixture is built to trip four checks once each: the Improved section is placed before the New section, so New is out of order. One New entry is tagged voice-notes, which is not one of the 5 slugs in the shipped fixture. One Fixed entry carries a banned hype word. One Fixed entry has no Effect: marker. The clean fixture carries the same 5 shipped items, all six sections in order, and no faults, and it passes. The shipped fixture holds the slugs dark-mode, export-csv, faster-search, login-timeout-fix, and crash-on-empty-title-fix.

release_check.py (Python 3, standard library only). Save this code as release_check.py:

python
#!/usr/bin/env python3
"""Check user-facing release notes against a shipped items list.

Usage:
  python3 release_check.py --make-fixture
  python3 release_check.py SHIPPED_FILE NOTES_FILE

--make-fixture writes shipped.txt, notes_good.md, and notes_bad.md
in the current folder. The shipped file holds one item slug per
line. The notes file is a Markdown document whose first line has
the shape: # Release X.Y.Z - YYYY-MM-DD

Sections are level-2 headings, expected in this order:
Breaking changes, Known issues, New, Improved, Fixed,
Upgrade steps. Breaking changes and Known issues are required.

Bullet entries in Breaking changes, Known issues, New, Improved,
and Fixed are checked for an Effect: marker. Bullet entries in
New, Improved, and Fixed are checked for a shipped item tag in
brackets at the start of the entry, matched against the shipped
list. Entries in New and Fixed are also checked against the
banned hype word list below.

Output prints one line per issue found, then summary counts, then
result: PASS or FAIL. Exit code is 0 on PASS, 1 on FAIL, and 2
on a usage or file error. Standard library only.
"""
import re
import sys

SECTION_ORDER = [
    "Breaking changes",
    "Known issues",
    "New",
    "Improved",
    "Fixed",
    "Upgrade steps",
]
REQUIRED_SECTIONS = ["Breaking changes", "Known issues"]
EFFECT_SECTIONS = [
    "Breaking changes",
    "Known issues",
    "New",
    "Improved",
    "Fixed",
]
TAGGED_SECTIONS = ["New", "Improved", "Fixed"]
HYPE_SECTIONS = ["New", "Fixed"]
HYPE_WORDS = [
    "game-changer",
    "revolutionary",
    "supercharge",
    "blazing-fast",
    "seamless",
    "cutting-edge",
    "world-class",
]
HEADER_RE = re.compile(r"^# Release \d+\.\d+\.\d+ - \d{4}-\d{2}-\d{2}\s*$")
TAG_RE = re.compile(r"^-\s+\[([^\]]+)\]")

SHIPPED_FIXTURE = (
    "dark-mode\n"
    "export-csv\n"
    "faster-search\n"
    "login-timeout-fix\n"
    "crash-on-empty-title-fix\n"
)

NOTES_GOOD = """# Release 2.4.0 - 2026-10-19

## Breaking changes
- The old export format is removed. Effect: exports saved in the old format no longer open, and the action is to re-export in the new format.

## Known issues
None

## New
- [dark-mode] Dark mode is available in settings. Effect: the app can be used in a dark theme.
- [export-csv] Reports can be exported as CSV files. Effect: report data can be opened in a spreadsheet.

## Improved
- [faster-search] Search returns results in fewer steps. Effect: results appear sooner on large accounts.

## Fixed
- [login-timeout-fix] Login no longer times out on slow connections. Effect: sign-in completes instead of failing.
- [crash-on-empty-title-fix] Saving an item with an empty title no longer stops the app. Effect: the save is refused with a message instead of a crash.

## Upgrade steps
1. Back up your data from the settings screen.
2. Install the update.
3. Open settings and confirm the version reads 2.4.0.
"""

NOTES_BAD = """# Release 2.4.0 - 2026-10-19

## Breaking changes
- The old export format is removed. Effect: exports saved in the old format no longer open, and the action is to re-export in the new format.

## Known issues
None

## Improved
- [faster-search] Search returns results in fewer steps. Effect: results appear sooner on large accounts.

## New
- [dark-mode] Dark mode is available in settings. Effect: the app can be used in a dark theme.
- [voice-notes] Voice notes can be recorded in items. Effect: notes can be dictated instead of typed.

## Fixed
- [crash-on-empty-title-fix] A revolutionary fix stops the crash on empty titles. Effect: the save is refused with a message instead of a crash.
- [login-timeout-fix] Login no longer times out on slow connections.

## Upgrade steps
1. Back up your data from the settings screen.
2. Install the update.
3. Open settings and confirm the version reads 2.4.0.
"""


def check(shipped, text):
    lines = text.splitlines()
    issues = []
    counts = {
        "header_issues": 0,
        "section_issues": 0,
        "hype_issues": 0,
        "missing_effect_issues": 0,
        "unshipped_issues": 0,
    }
    if not lines or not HEADER_RE.match(lines[0]):
        counts["header_issues"] += 1
        issues.append("issue: line 1: header: first line is not a release header")
    sections_found = []
    max_order = -1
    current = None
    entries_checked = 0
    effect_entries_checked = 0
    for idx, line in enumerate(lines, start=1):
        stripped = line.strip()
        if stripped.startswith("## "):
            name = stripped[3:].strip()
            if name in SECTION_ORDER:
                sections_found.append(name)
                order = SECTION_ORDER.index(name)
                if order < max_order:
                    counts["section_issues"] += 1
                    issues.append(
                        f"issue: line {idx}: out_of_order: section out of order: {name}"
                    )
                else:
                    max_order = order
                current = name
            else:
                current = None
            continue
        if current in EFFECT_SECTIONS and stripped.startswith("- "):
            effect_entries_checked += 1
            if current in TAGGED_SECTIONS:
                entries_checked += 1
                m = TAG_RE.match(stripped)
                slug = m.group(1).strip() if m else None
                if slug is None or slug not in shipped:
                    counts["unshipped_issues"] += 1
                    label = slug if slug else "missing-tag"
                    issues.append(
                        f"issue: line {idx}: unshipped_claim: item not in shipped list: {label}"
                    )
            if current in HYPE_SECTIONS:
                low = stripped.lower()
                for word in HYPE_WORDS:
                    if word in low:
                        counts["hype_issues"] += 1
                        issues.append(
                            f"issue: line {idx}: hype_word: entry in {current} contains banned hype word: {word}"
                        )
                        break
            if "Effect:" not in stripped:
                counts["missing_effect_issues"] += 1
                issues.append(
                    f"issue: line {idx}: missing_effect: entry in {current} has no Effect: marker"
                )
    required_missing = sum(1 for s in REQUIRED_SECTIONS if s not in sections_found)
    total = sum(counts.values()) + required_missing
    for issue in issues:
        print(issue)
    print(f"sections_found: {len(sections_found)}")
    print(f"required_missing: {required_missing}")
    print(f"entries_checked: {entries_checked}")
    print(f"effect_entries_checked: {effect_entries_checked}")
    print(f"header_issues: {counts['header_issues']}")
    print(f"section_issues: {counts['section_issues']}")
    print(f"hype_issues: {counts['hype_issues']}")
    print(f"missing_effect_issues: {counts['missing_effect_issues']}")
    print(f"unshipped_issues: {counts['unshipped_issues']}")
    print(f"total_issues: {total}")
    print(f"result: {'PASS' if total == 0 else 'FAIL'}")
    return 0 if total == 0 else 1


def make_fixture():
    with open("shipped.txt", "w", encoding="utf-8") as fh:
        fh.write(SHIPPED_FIXTURE)
    with open("notes_good.md", "w", encoding="utf-8") as fh:
        fh.write(NOTES_GOOD)
    with open("notes_bad.md", "w", encoding="utf-8") as fh:
        fh.write(NOTES_BAD)
    print("wrote shipped.txt, notes_good.md, notes_bad.md")
    return 0


def main():
    args = sys.argv[1:]
    if args == ["--make-fixture"]:
        return make_fixture()
    if len(args) != 2:
        print("usage: release_check.py SHIPPED_FILE NOTES_FILE")
        print("       release_check.py --make-fixture")
        return 2
    try:
        with open(args[0], encoding="utf-8") as fh:
            shipped = [ln.strip() for ln in fh if ln.strip()]
        with open(args[1], encoding="utf-8") as fh:
            text = fh.read()
    except OSError as exc:
        print(f"error: {exc}")
        return 2
    return check(shipped, text)


if __name__ == "__main__":
    raise SystemExit(main())

Versions

v1.0.02026-10-20 · 0 installs · Ed25519-signed./install.sh release-notes-writing 1.0.0bundle (.zip)

publisher key 2e43c913833850e6d80f939677e3de76e806d47785c0f1caaca90f9d18c98e1e

Ratings

No ratings yet — be the first to rate it.