AGENTS.md:66 states: "CHANGELOG entries: terse, scannable, imperative, under the Unreleased heading." The file has drifted well away from that, and the rule is now unenforceable in review because nobody can say what "too long" means when the surrounding entries are much longer.
Measured on port/rename-resolution, line counts per bullet in the ## [Unreleased] section:
| lines |
count |
| 3–9 |
28 |
| 10–15 |
15 |
| 16–25 |
6 |
| 33, 35, 53, 57 |
4 |
So the median entry is under 10 lines but the tail runs to 57. A ~20-line entry — the one that prompted this — sits mid-distribution, which means the rule as written flags it while ~10 longer entries around it pass unremarked.
This surfaced on #436, where a bot correctly cited AGENTS.md:66 against the #393 entry. The finding was right about the rule and wrong about the remedy: restructuring that one entry into imperative bullets would have made it an outlier against ~50 narrative neighbours, and would have rewritten text already shipped in an earlier commit on the same PR. Deferred deliberately rather than resolved there.
The decision to make — pick one, then make it checkable:
- The rule is right; the file drifted. Tighten the long tail and add a length guide (e.g. "one bullet, ≤ 8 lines; move the narrative into the docs it belongs to"). Highest cost, best long-term scannability.
- The practice is right; the rule is stale. These are release-note entries doing real explanatory work — several are the only prose record of a subtle mechanism. Reword
AGENTS.md:66 to describe what the file actually does (lead with an imperative bold summary line, narrative body permitted).
- Split the difference. Require a terse bold lead sentence that reads alone, and allow the body to run — which most long entries already do informally.
Option 3 is closest to current practice and would make the rule enforceable without a rewrite.
Whichever wins, the rule should name a concrete limit or explicitly say there is none, so a reviewer citing it has something objective to point at.
AGENTS.md:66states: "CHANGELOG entries: terse, scannable, imperative, under the Unreleased heading." The file has drifted well away from that, and the rule is now unenforceable in review because nobody can say what "too long" means when the surrounding entries are much longer.Measured on
port/rename-resolution, line counts per bullet in the## [Unreleased]section:So the median entry is under 10 lines but the tail runs to 57. A ~20-line entry — the one that prompted this — sits mid-distribution, which means the rule as written flags it while ~10 longer entries around it pass unremarked.
This surfaced on #436, where a bot correctly cited
AGENTS.md:66against the#393entry. The finding was right about the rule and wrong about the remedy: restructuring that one entry into imperative bullets would have made it an outlier against ~50 narrative neighbours, and would have rewritten text already shipped in an earlier commit on the same PR. Deferred deliberately rather than resolved there.The decision to make — pick one, then make it checkable:
AGENTS.md:66to describe what the file actually does (lead with an imperative bold summary line, narrative body permitted).Option 3 is closest to current practice and would make the rule enforceable without a rewrite.
Whichever wins, the rule should name a concrete limit or explicitly say there is none, so a reviewer citing it has something objective to point at.