docs(skills): changelog entries describe deltas, not repeats (#11663)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Stable release notes are drafted per release from the commit range
since the previous stable
> - Features evolve across consecutive releases, so a correct range
still produces entries that re-describe what the previous notes already
introduced
> - The first channel-train draft did exactly that for four themes, and
review caught it against the published previous changelog
> - This pull request adds the missing framing rule to the changelog
skill and mirrors it in the Discord skill
> - The benefit is that consecutive releases read as a progression
instead of repeating themselves

## Linked Issues or Issue Description

**What existing behavior does this improve?**

The authoring guidance in `.agents/skills/release-changelog/SKILL.md`
and `.agents/skills/release-changelog-discord-message/SKILL.md`.

**Current behavior**

The skills define the range and the sections but say nothing about
features the previous stable's notes already introduced. A draft for a
follow-up release naturally re-describes them as if they debuted
(observed in the v2026.821.0 draft: the chat conversation view, sandbox
output streaming, the raised import cap, and the channel system — all
already announced in v2026.817.0's notes).

**Proposed behavior**

The changelog skill instructs the author to read the previous stable's
notes first and phrase already-introduced features as deltas ("last
release introduced X; this release makes it the default"), demoting
follow-through themes out of Highlights. The Discord skill's highlight
guidance mirrors the rule.

**Reason and benefit**

Consecutive changelogs read as a progression; readers of both releases
never see the same debut twice.

## What Changed

- `.agents/skills/release-changelog/SKILL.md`: a "describe deltas, not
repeats" guideline in Step 4, with the read-the-previous-notes
instruction and the headline-demotion rule.
- `.agents/skills/release-changelog-discord-message/SKILL.md`: one
mirrored bullet in the template notes.

## Verification

- Docs-only; proofread. The rule matches the fix applied to the live
v2026.821.0 draft (#11661), which is the worked example of what it
prevents.

## Risks

- None; docs-only.

## Model Used

Claude Fable 5 (Claude Code)

## Pre-submission checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
This commit is contained in:
Devin Foley 2026-08-18 16:41:00 -07:00 committed by GitHub
parent ffaac1d7f9
commit 927ef58d04
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 11 additions and 0 deletions

View File

@ -163,6 +163,9 @@ Mimic this register; do not invent a "professional" tone.
- **"WHATS NEXT" is forward-looking themes**, not a literal sprint list. 35
bullets is the right size. Pull these from active goals, in-flight projects,
and recent issues the team is working on — do not invent themes.
- **Highlights follow the changelog skill's delta rule**: a feature the
previous announcement already introduced appears only for what changed
this release, and does not headline twice for follow-through work.
- **"What's on my mind"** is dotta's personal/strategic thinking — docs gaps,
philosophical positioning ("we're the human control plane for ai labor"),
invitations ("if you've ever wanted to write about how you use Paperclip,

View File

@ -168,6 +168,14 @@ Guidelines:
- write from the user perspective
- keep highlights short and concrete
- spell out upgrade actions for breaking changes
- **describe deltas, not repeats**: read the previous stable's notes
(`releases/v<last-stable>.md`) before writing. When they already
introduced a feature, this release's entry covers only what changed —
a default flip, a hardening, a completion — phrased against the prior
release ("last release introduced X; this release makes it the
default"), never re-describing the feature as if it debuted. A theme
that headlined the previous release does not headline again for
follow-through work; demote it to Improvements.
### Inline PR and contributor attribution