From 927ef58d04f2b1b40e623716218be0978f86f1a3 Mon Sep 17 00:00:00 2001 From: Devin Foley Date: Tue, 18 Aug 2026 16:41:00 -0700 Subject: [PATCH] docs(skills): changelog entries describe deltas, not repeats (#11663) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 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 --- .agents/skills/release-changelog-discord-message/SKILL.md | 3 +++ .agents/skills/release-changelog/SKILL.md | 8 ++++++++ 2 files changed, 11 insertions(+) diff --git a/.agents/skills/release-changelog-discord-message/SKILL.md b/.agents/skills/release-changelog-discord-message/SKILL.md index 7852ad1a83..cd8cc50af3 100644 --- a/.agents/skills/release-changelog-discord-message/SKILL.md +++ b/.agents/skills/release-changelog-discord-message/SKILL.md @@ -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, diff --git a/.agents/skills/release-changelog/SKILL.md b/.agents/skills/release-changelog/SKILL.md index da1d141d33..55e7b360ea 100644 --- a/.agents/skills/release-changelog/SKILL.md +++ b/.agents/skills/release-changelog/SKILL.md @@ -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.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