changelog-bullet
Skill9 starsChanged 47 days agoApache-2.0View on GitHub
Write the CHANGELOG entry for a core-agent PR. Use whenever a change is user-visible — a feature, bug fix, published-doc or contributor-rule change, breaking change or cleanup. Covers which subsection, citing the issue rather than the PR, what a bullet has to contain, and the stacked-release-branch hazard that silently files a bullet under a shipped version.
In this repository10 other files it gives its agents.
- .agents/AGENTS.mdAGENTS.md
- AGENTS.mdAGENTS.md
- .agents/reviewer/AGENTS.mdAGENTS.md
- adversarial-review-gateSkill
- prefix-failure-verificationSkill
- presubmit-sweepSkill
- stacked-pr-orderSkill
- autonomous-setupSkill
- cli-setupSkill
- library-embeddingSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Every merged PR with a user-visible change adds one bullet under ## [Unreleased] in CHANGELOG.md, as part of the PR itself.
- Very specific: line 21
No for everything else under docs/ and dev/.
- Very specific: line 71
No check catches the duplicate version heading automatically: verify-release-notes checks [Unreleased] bullets on CHANGELOG.md, not …
- Distinctive: line 76
After any base-update on such a branch:
- Very specific: line 87
Run dev/ci/presubmits/verify-release-notes before pushing.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
The CHANGELOG bullet
Every merged PR with a user-visible change adds one bullet under
## [Unreleased] in CHANGELOG.md, as part of the PR itself. Both
release scripts assume [Unreleased] is current; if it is stale at tag time
someone has to backfill it from git log, which produces a worse entry than
the person who made the change would have.
Does a doc change need one?
Yes for three kinds: the published site under docs/site/src/content/docs/;
README.md and the READMEs under examples/; and a change to a rule in
AGENTS.md, CONTRIBUTING.md, docs/release-process.md or a skill under
.agents/. All three go under #### Documentation.
No for everything else under docs/ and dev/. Design docs, assessments,
UAT write-ups and friction logs are internal. When an internal doc records a
user-visible change, the bullet belongs to that change, not to the doc.
This is AGENTS.md's "Which doc changes are user-visible" rule, and if the
two ever disagree, AGENTS.md wins. Don't infer the rule from
CHANGELOG.md's history. Before the rule, docs-only PRs almost never
carried a bullet, even though the text said they should.
Which subsection
#### Feature · #### Bug or Regression · #### Documentation ·
#### Other (Cleanup) · #### Security
Breaking changes go under #### Changed with a **BREAKING:** prefix, so
cut-ga-tag.sh can hoist them into a ### Breaking Changes section
automatically at tag time.
Cite the issue, not the PR
([#1137](https://github.com/go-steer/core-agent/issues/1137))The issue is where the problem is described and where the discussion lives. The PR number is recoverable from git; the issue number is the one a reader six months out actually wants.
What a bullet has to contain (<= 300 characters)
Each [Unreleased] bullet is a single line capped at 300 characters
(enforced by dev/tools/verify-release-notes), ending with a
([#NNN](https://github.com/go-steer/core-agent/issues/NNN)) link. The
long-form rationale, rejected alternatives, and incident history belong in
the PR body or docs/, so CHANGELOG.md and the GitHub Release body stay
readable and well under GitHub's 125 KB release-body limit (#1387).
- Lead with what changed in the user's terms, bolded, naming the affected package or surface.
- State the concrete effect or fix in one concise sentence.
- End with the issue link
([#NNN](url)).
The hazard worth memorizing
A base-update on a branch stacked on a release-promotion PR silently
duplicates the CHANGELOG version heading. Both sides carry the identical
## [Unreleased] → ## [X.Y.Z] — DATE rename, git resolves two identical
insertions without a conflict, and your bullet ends up filed under a
release that was tagged from a commit demonstrably lacking it.
No check catches the duplicate version heading automatically:
verify-release-notes checks [Unreleased] bullets on CHANGELOG.md, not
duplicate version headings, and verify-docs-lint passes on the duplicated
file.
After any base-update on such a branch:
git diff <base>...HEAD -- CHANGELOG.md # three-dot, not the merge exit code
grep -nE '^## \[' CHANGELOG.md | headObserved on #993.
Also
Run dev/ci/presubmits/verify-release-notes before pushing. If the change
touches a user-visible surface, the Astro site under
docs/site/src/content/docs/ walks in the same PR, not as a follow-up.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

