Reviewed every PR that touched changelog/index.mdx (#322, #327, #333, #342, #352, #357, #362, #370, #371, #376, #388) and all 49 inline review comments on them. The same handful of subjects recur, and most are cheap to prevent in .mintlify/workflows/update-changelog.md rather than catch in review.
Findings are ordered by how often they actually cost a review round.
1. British spelling — 9 comments across 4 PRs, and the stated safety net does not work
Flagged in #342 (behaviour), #352 (cancelled ×2, unrecognised, honours, plus one repeat because a "fix: use American spelling" commit missed one), #362 (labelled, defence), #376 (serialised ×2, the second because the first suggestion went stale).
The instruction says:
Before opening a PR, review all written content against the style rules in styles/Kosli/. In particular, AmericanSpelling.yml maps British spellings to their American equivalents
That is circular. styles/Kosli/AmericanSpelling.yml contains only six word-families — organisation, organise, behaviour, colour, standardise, categorise. Every word ever flagged in review except behaviour is absent from it, so consulting the file cannot catch them and neither can Vale.
Two changes, and the first matters more:
- Extend
styles/Kosli/AmericanSpelling.yml with at least the words that have actually appeared: serialise/serialised/serialising, cancelled/cancelling, labelled/labelling, defence, unrecognised, honour/honours/honoured, licence (noun), initialise/initialised, authorise/authorised, analyse/analysed, prioritise/prioritised. That moves enforcement to CI, where it belongs, and helps every author rather than only this workflow.
- Stop pointing the workflow at the file as if it were a checklist. Say "use American spelling" and name the recurring traps inline.
Worth checking as part of this: behaviour is in the swap list and was still flagged in #342 (July 27), after the rule landed (June 3). Either the Vale check is non-blocking or it did not run — worth knowing which before relying on it.
2. Non-user-facing changes keep getting entries — 4 PRs, all three human reviewers
The current instruction is about information, not about the change:
Do not include internal-only information such as: Private repository file paths…, Code snippets, internal function names, or implementation details
An entry can contain none of those and still describe a change no user can observe. Add explicit exclusions:
- Build, release-pipeline, CI, or container-publishing changes, unless a user-visible artifact changes (a published image reporting the wrong version is user-visible; a smoke test going red is not).
- Test-only changes and refactors.
- Anything behind a feature flag, until the flag is removed.
- A follow-up that supersedes an earlier internal approach without changing behavior.
And two heuristics that would have caught every instance above:
3. Announcing features the docs do not document — 3 PRs
There is a standing rule here that the workflow never states: do not write an entry for a subject the docs do not cover. A reader who learns a feature exists and finds nothing to read is worse off than one who never saw the entry.
Add it, generalized beyond SCIM: before writing an entry, grep the docs for the feature. If nothing documents it, skip the entry and note the gap in the PR description so a docs issue can be filed.
4. Entries that contradict live docs — the highest-severity class
#376's Spaces entry announced that the org-level opt-in setting was gone, while tutorials/organizing_with_spaces.mdx still listed enabling it as step 3 — a dead prerequisite that would make a reader conclude Spaces was unavailable to them. The changelog was right and the tutorial was left wrong.
Add: when an entry announces that a setting, flag, or capability has been removed or changed, grep the docs for it. Fix the affected page in the same PR, or name it in the PR description. This is the one class where the workflow's "only updates changelog/index.mdx" constraint actively causes harm — it should be allowed to flag, even if not to edit.
5. Command names that do not exist — 2 PRs, both Critical
Both names were lifted from upstream release-note prose, which is written for people who know the CLI. Since v2.36.0 an unknown command exits non-zero, so a reader copying either gets a hard failure.
Add: verify every command you name against client_reference/. The generated filename is the command path — kosli_snapshot_azure.md ⇒ kosli snapshot azure. If there is no such file, the command does not exist.
6. Reference links — missing, mismatched, or not backing the claim — 3 PRs
Add: name a command ⇒ link its generated reference page. Link text must match the target. And check the target actually documents the claim, not merely that the anchor resolves.
7. Chronological ordering — 2 PRs, one of them a dedicated human fix
#370 put an August 17 block above an existing August 18 entry. #371 exists solely as "chore: fix ordering and a typo".
The instruction says the label is the release date but never says entries are ordered by it. Add: entries are strictly reverse-chronological by label date; insert by date rather than prepending. #388's four-way rebase conflict was a downstream symptom of prepend-by-default.
8. ## Breaking changes is missing from the section list
The instruction gives three sections:
- New features 2. Updates 3. Bug fixes
changelog/index.mdx has four ## Breaking changes headings already. #376 filed a capability removal under "Updates" and review had to move it. Add it as the first section, with a note that removing or restricting an existing capability belongs there even when the release notes call it an improvement.
9. Duplicate entries from a stale base — #388
#388 was generated from a base predating #376 and re-added v2.39.0 and v2.39.1 in different wording, producing four rebase conflicts and needing manual reconciliation to keep the reviewed text while salvaging one genuinely new bullet.
Add: determine the last documented version by reading changelog/index.mdx on current main at the time of the run, and check for an open changelog PR from a previous run before writing. If one exists, extend it rather than opening a second.
10. Jargon and unactionable detail — #388
"tree state" (git jargon) and "since at least May 2024" — readers pin images by tag, not by date, so the actionable boundary is the version.
Add: describe the symptom a reader can observe, and give boundaries as versions rather than dates.
11. PR title type does not match the instruction
The instruction says:
Use docs: as the type.
Actual titles: chore: on #388, #376, #370, #362, #342, #333, #327; docs: on #357, #352, #322. Seven of ten ignore it. Either the instruction is not being followed or chore: is the right type for a changelog-only change — worth settling and then stating once, since pr-quality.yml enforces the format but not the type.
Suggested shape
Most of the above is a short pre-flight checklist rather than more prose. Something like:
Before opening the PR, verify:
- [ ] Every command named exists in client_reference/ (filename = command path)
- [ ] Every named command links its reference page; link text matches target
- [ ] Any linked anchor actually documents the claim
- [ ] Entries are reverse-chronological by label date
- [ ] Removals/restrictions are under "## Breaking changes"
- [ ] No build/CI/test-only, feature-flagged, or behavior-preserving changes
- [ ] Nothing announced that the docs do not document
- [ ] Nothing announced that contradicts a live page (grep for removed settings)
- [ ] American spelling
- [ ] No open changelog PR from a previous run
Happy to draft the actual edit to .mintlify/workflows/update-changelog.md plus the AmericanSpelling.yml additions if this looks right.
Reviewed every PR that touched
changelog/index.mdx(#322, #327, #333, #342, #352, #357, #362, #370, #371, #376, #388) and all 49 inline review comments on them. The same handful of subjects recur, and most are cheap to prevent in.mintlify/workflows/update-changelog.mdrather than catch in review.Findings are ordered by how often they actually cost a review round.
1. British spelling — 9 comments across 4 PRs, and the stated safety net does not work
Flagged in #342 (
behaviour), #352 (cancelled×2,unrecognised,honours, plus one repeat because a "fix: use American spelling" commit missed one), #362 (labelled,defence), #376 (serialised×2, the second because the first suggestion went stale).The instruction says:
That is circular.
styles/Kosli/AmericanSpelling.ymlcontains only six word-families —organisation,organise,behaviour,colour,standardise,categorise. Every word ever flagged in review exceptbehaviouris absent from it, so consulting the file cannot catch them and neither can Vale.Two changes, and the first matters more:
styles/Kosli/AmericanSpelling.ymlwith at least the words that have actually appeared:serialise/serialised/serialising,cancelled/cancelling,labelled/labelling,defence,unrecognised,honour/honours/honoured,licence(noun),initialise/initialised,authorise/authorised,analyse/analysed,prioritise/prioritised. That moves enforcement to CI, where it belongs, and helps every author rather than only this workflow.Worth checking as part of this:
behaviouris in the swap list and was still flagged in #342 (July 27), after the rule landed (June 3). Either the Vale check is non-blocking or it did not run — worth knowing which before relying on it.2. Non-user-facing changes keep getting entries — 4 PRs, all three human reviewers
The current instruction is about information, not about the change:
An entry can contain none of those and still describe a change no user can observe. Add explicit exclusions:
And two heuristics that would have caught every instance above:
3. Announcing features the docs do not document — 3 PRs
There is a standing rule here that the workflow never states: do not write an entry for a subject the docs do not cover. A reader who learns a feature exists and finds nothing to read is worse off than one who never saw the entry.
Add it, generalized beyond SCIM: before writing an entry, grep the docs for the feature. If nothing documents it, skip the entry and note the gap in the PR description so a docs issue can be filed.
4. Entries that contradict live docs — the highest-severity class
#376's Spaces entry announced that the org-level opt-in setting was gone, while
tutorials/organizing_with_spaces.mdxstill listed enabling it as step 3 — a dead prerequisite that would make a reader conclude Spaces was unavailable to them. The changelog was right and the tutorial was left wrong.Add: when an entry announces that a setting, flag, or capability has been removed or changed, grep the docs for it. Fix the affected page in the same PR, or name it in the PR description. This is the one class where the workflow's "only updates
changelog/index.mdx" constraint actively causes harm — it should be allowed to flag, even if not to edit.5. Command names that do not exist — 2 PRs, both Critical
kosli snapshot azure-apps.azure-appsis an environment type (kosli create environment --type), never a subcommand. The command iskosli snapshot azure.kosli update attestation-type. Onlyarchive/create/get/listexist; updating is re-runningcreate.Both names were lifted from upstream release-note prose, which is written for people who know the CLI. Since v2.36.0 an unknown command exits non-zero, so a reader copying either gets a hard failure.
Add: verify every command you name against
client_reference/. The generated filename is the command path —kosli_snapshot_azure.md⇒kosli snapshot azure. If there is no such file, the command does not exist.6. Reference links — missing, mismatched, or not backing the claim — 3 PRs
--summary-json(the alternative form) and omitted--summary(the primary one).kosli attest, target waskosli_attest_artifact.#policy-expressions, which resolved but did not state the rule being announced.mint broken-linkspasses on a link like this, so only a human catches it.Add: name a command ⇒ link its generated reference page. Link text must match the target. And check the target actually documents the claim, not merely that the anchor resolves.
7. Chronological ordering — 2 PRs, one of them a dedicated human fix
#370 put an August 17 block above an existing August 18 entry. #371 exists solely as "chore: fix ordering and a typo".
The instruction says the label is the release date but never says entries are ordered by it. Add: entries are strictly reverse-chronological by label date; insert by date rather than prepending. #388's four-way rebase conflict was a downstream symptom of prepend-by-default.
8.
## Breaking changesis missing from the section listThe instruction gives three sections:
changelog/index.mdxhas four## Breaking changesheadings already. #376 filed a capability removal under "Updates" and review had to move it. Add it as the first section, with a note that removing or restricting an existing capability belongs there even when the release notes call it an improvement.9. Duplicate entries from a stale base — #388
#388 was generated from a base predating #376 and re-added v2.39.0 and v2.39.1 in different wording, producing four rebase conflicts and needing manual reconciliation to keep the reviewed text while salvaging one genuinely new bullet.
Add: determine the last documented version by reading
changelog/index.mdxon currentmainat the time of the run, and check for an open changelog PR from a previous run before writing. If one exists, extend it rather than opening a second.10. Jargon and unactionable detail — #388
"tree state" (git jargon) and "since at least May 2024" — readers pin images by tag, not by date, so the actionable boundary is the version.
Add: describe the symptom a reader can observe, and give boundaries as versions rather than dates.
11. PR title type does not match the instruction
The instruction says:
Actual titles:
chore:on #388, #376, #370, #362, #342, #333, #327;docs:on #357, #352, #322. Seven of ten ignore it. Either the instruction is not being followed orchore:is the right type for a changelog-only change — worth settling and then stating once, sincepr-quality.ymlenforces the format but not the type.Suggested shape
Most of the above is a short pre-flight checklist rather than more prose. Something like:
Happy to draft the actual edit to
.mintlify/workflows/update-changelog.mdplus theAmericanSpelling.ymladditions if this looks right.