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:
parent
ffaac1d7f9
commit
927ef58d04
|
|
@ -163,6 +163,9 @@ Mimic this register; do not invent a "professional" tone.
|
|||
- **"WHATS NEXT" is forward-looking themes**, not a literal sprint list. 3–5
|
||||
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,
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue