Changelog writer

Changelog Writer

Writes external, end-user-facing changelog entries with personality — modeled on what Slack, Basecamp, Linear, Raycast, and Tumblr do well: voice and confidence first, jokes used sparingly and only in service of the fact, never replacing it.

This skill is for external/end-user changelogs. If the audience is internal engineering or the changelog needs to double as a searchable technical record (breaking changes, API versioning, migration notes), this tone is the wrong trade — use a precise, Stripe-style format instead and skip this skill.

Reference files:

• references/voice-examples.md — annotated examples of the tone done well (Slack, Basecamp, Tumblr, Raycast, Linear) and done badly, for calibration
• references/draft-format.md — the full spec for the intermediate draft format the scripts parse

Scripts (in scripts/) — run these against every draft before presenting a final version:

• check-all.mjs — runs everything below and gives one pass/fail report
• check-structure.mjs, check-sass-budget.mjs, check-voice.mjs, check-length.mjs, check-cadence.mjs

---

Workflow

1. Gather the raw material. Get the list of what actually shipped — feature names, what changed, any tickets/PRs. If it's vague ("we improved search"), ask what specifically changed before writing anything. A joke can't rescue an entry with no real content behind it.
2. Group by theme, not by ticket. Five related tweaks become one entry. Assign each entry a category (New, Improved, or Fixed) and a stable id (a slug from the feature name, not a sequence number — this is what makes the rule IDs and scripts useful over time, since entries can be tracked and diffed release over release).
3. Draft every entry in the structured format described in references/draft-format.md. Write the whole draft this way first — plain field-by-field — before making it pretty. This is what makes the entry checkable by script instead of just vibes.
4. Run node scripts/check-all.mjs <draft-file>. Fix every FAIL. Read every WARN and use judgment — WARNs are things worth a second look, not always things to change.
5. Re-run until clean, then convert the structured draft into the final published prose (see "Rendering the final version" below).
6. Present the finished changelog, not the structured intermediate format — the field labels are a drafting tool, not something an end user should ever see.

---

The building blocks (rule reference)

Every rule below has a stable ID. The scripts check the ones marked [scripted]; the rest are judgment calls a script can't reliably make — apply them yourself when drafting.

Entry skeleton — STRUCT-*

• STRUCT-01 (scripted) — Headline is mandatory. Plain statement of what shipped, no pun required. Whoever's skimming has to get this in one glance.
• STRUCT-02 (scripted) — So-what is mandatory for New/Improved entries (optional, can collapse into the headline for Fixed). One sentence on why this matters to the reader, written like you're telling a friend, not pitching a feature.
• STRUCT-03 (scripted) — Receipt is mandatory for New/Improved entries. The actual detail: what changed, what to click, what's different. Always plain English, never vague ("various improvements" fails this check).
• STRUCT-04 — Hook is optional and the only piece allowed to be cut. Better no joke than a forced one.

Sass budget — SASS-*

• SASS-01 (scripted) — One bit per entry, max. If the headline already lands a joke, the hook stays quiet.
• SASS-02 (scripted) — Zero jokes near security, billing, data loss, outages, or anything users would be upset about. Straight talk only. This is a hard rule, not a style preference.
• SASS-03 (scripted, batch-level, warn only) — Not every entry needs a bit. If most entries in one release have a hook, personality has stopped being special.

Voice — VOICE-*

• VOICE-01 (scripted) — No corporate buzzwords or press-release phrasing ("we are pleased to announce," "leverage," "seamless experience," "blazing fast" — say the actual number instead).
• VOICE-02 (scripted, warn only) — Use contractions. Formal constructions read stiff.
• VOICE-03 (scripted) — No clichéd pun templates (egg-cellent, purr-fect, fin-tastic, and the like — swap-a-word-for-a-similar-sounding-word puns that are worn out regardless of the feature) and no lampshading ("get it?", "pun intended", a winking emoji). If a joke has to announce itself, it already failed.
• VOICE-04 (judgment only, not scripted) — The "two truths, one phrase" test: a pun is only good if its second meaning is also literally true of what shipped, not just wordplay that happened to be available. A script can't know what's true about the feature, so this one's on you. See references/voice-examples.md for the full breakdown.

Length — LEN-*

• LEN-01 (scripted) — Fixed entries: ~30 words total across all filled fields. Should read in one breath.
• LEN-02 (scripted) — New/Improved entries: 4 sentences max combined across all fields.
• LEN-03 (scripted) — No single field over 40 words. If it needs a paragraph, the feature is confusing, not the changelog.

Cadence / metadata — CAD-*

• CAD-01 (scripted) — Category must be New, Improved, or Fixed. Nothing fancier — the categories aren't where the personality goes.
• CAD-02 (scripted, warn only) — Every entry needs a unique, stable id (a slug, not a sequence number), so entries can be tracked release over release.
• CAD-03 (judgment only) — Ship an entry every release, even a boring one. Consistency is what earns the reader's trust that the funny ones are worth reading.

---

Rendering the final version

Once a draft passes check-all.mjs clean, convert each entry from the structured fields into one flowing changelog entry:

## [Headline, possibly rewritten as a title]
[Hook, if present — one line, woven in naturally] [So-what, one line] [Receipt, the actual detail]
[CTA, if present]

Group entries under New, Improved, Fixed headers, in that order. Don't show the reader headline: / hook: / etc. labels — those are scaffolding for the check, not part of the output.

Example — structured draft:

### ENTRY id=bulk-actions category=New sass=hook
headline: Bulk actions have entered the chat.
hook: You can now select every unread thread at once.
sowhat: Stop clicking the same checkbox forty times.
receipt: Select multiple conversations from the inbox and archive, tag, or reassign them in one action.
cta: none
### END

Rendered as:

Bulk actions have entered the chat. Select every unread thread at once instead of clicking the same checkbox forty times — archive, tag, or reassign a whole batch in one go.

---

Common failure mode to watch for

The most common way this goes wrong isn't "not funny enough" — it's overwritten. Every entry trying too hard, reader fatigue setting in by the third one. When in doubt, cut the hook before you cut the receipt. The fact always survives; the bit is expendable.