# rd-changelog

> Turn the issues completed since a date or a tag into Feature, Improvement and Fix entries in customer language.

`rd-changelog` collects the work that reached a completed status in a window,
reads each issue's body rather than its title, and writes entries a customer
would understand. It asks about anything that looks internal instead of
inventing a user benefit for a refactor.

> Write the changelog from what actually shipped in Radial, the keyboard-first
> issue tracker: the issues completed since a date or a tag, read as Feature,
> Improvement and Fix entries in customer language rather than issue titles.

## When to use it

Cutting a release, or writing the weekly update. Not to find out what is left:
that is `/rd-triage`.

## What it asks you

The window, if you have not given one: a date, a tag, or nothing, in which
case it takes the date of the newest section already in the changelog and says
which date it chose. Then it asks about each issue it could not classify,
rather than guessing. An issue whose body does not say what changed for a user
becomes a question, never a sentence.

## What it writes

A dated section prepended to `.radial/changelog.md`, creating the file if it is
absent and preserving everything already in it: it reads the file, builds the
new content and writes it back whole, because appending to the end of a file
whose newest entry is at the top is how a changelog quietly becomes two
changelogs. The `output` hook sends it somewhere else instead. It writes
nothing to Radial.

## What an entry looks like

```markdown
## 2026-09-14

### Features
- Radial skills for Claude Code and Codex. `radial skills install` gives your
  agent the eleven rd-* workflows.

### Improvements
- Bare issue numbers now resolve in search.

### Fixes
- The comments panel opens only for files that have comments.
```

It says what a person can now do, in their words. "Search finds bare issue
numbers" beats "resolve numeric tokens in the search index". No issue key, no
internal component name, no branch name. One sentence, two at most: a third
sentence is a blog post.

Work with no user-visible effect gets no entry. A refactor, a test, a
dependency bump: listed under "Internal" only if you ask for that section, and
never given a manufactured benefit.

## Extension points

<hook-table skill="rd-changelog">
</hook-table>

## A worked wrapper

```markdown
---
name: public-changelog
description: Publish the changelog to the docs site in our house voice.
extends: rd-changelog
---

Read rd-changelog first, then apply the sections below at their hooks.

## extra-sources

- Include anything with a `shipped` label even if its status is not completed.
- Cross-check against `gh release list --limit 5`.

## entry-bar

- Second person, present tense. "You can now…" rather than "Users can now…".
- No entry over 20 words. Cut the clause, not the fact.
- Every Feature entry links to its docs page or is not a Feature.

## output

- Write to `content/changelog/<date>.mdx` with frontmatter `title` and `date`,
  instead of `.radial/changelog.md`.
```

## What it never does

It never invents a user-visible benefit for work that has none. It never
overwrites or truncates an existing changelog: prior sections survive byte for
byte. It never closes or edits an issue, and never puts an issue key or a
branch name in customer-facing text.