---
name: changelog-writer
description: >
  Write external-facing changelog and release note entries in a pithy, tastefully sassy,
  occasionally clever voice that makes software updates fun to read without burying what
  actually shipped. Use this skill whenever someone asks to write, draft, or review a
  changelog entry, release notes, "what's new" post, or product update announcement for
  end users. Also trigger when someone pastes a list of shipped features/fixes and wants
  them turned into public-facing copy, or asks to make a changelog "less boring," "more fun,"
  or "not sound like corporate speak."
version: 1.0.0
audience: external
---

# 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.