review-release-notes

# Review Release Notes Audit a scored `features.json` file and its markdown draft from the perspective of the **reader**, not the implementer. This is the **editorial QA stage** of the pipeline. Its job is to make sure the release notes feel curated, legible, and exciting to the right audience — not like an API inventory. This skill **reuses the shared rubric** from [`editorial-scoring`](../editorial-scoring/SKILL.md). It critiques the scoring; it does not invent a separate scoring philosophy. ## When to use - After `generate-features` produced `features.json` - After `release-notes` drafted the markdown - Before finalizing a milestone or a refreshed draft - When the selection feels too broad, too niche, or too internally focused - When you want to compare the current draft against the examples and recalibrate the cut ## Inputs Review these, in order: 1. `changes.json` — the source of truth for what shipped 2. `features.json` — the shipped-change entries with scored candidates 3. Draft markdown files (`libraries.md`, `runtime.md`, `sdk.md`, etc.) from each component PR branch if unmerged, or the milestone base branch if merged 4. Editorial examples in `references/examples/` 5. The scoring and quality bar references: - `../editorial-scoring/SKILL.md` - `references/feature-scoring.md` - `references/quality-bar.md` Before reviewing, compare `features.json` with `changes.json`: both must have the same change IDs and commit keys, including when the arrays are empty because nothing shipped. Confirm that noteworthy candidates have a `score` and `score_reason`; individual low-value entries may remain unscored, and a milestone with no noteworthy candidates need not invent any. If the file is missing, is a placeholder, drops shipped entries or commit keys, or lacks triage for noteworthy candidates, stop the review and complete `generate-features` first. Do not infer scores from the draft as a substitute for the shared triage stage. Compare noteworthy candidates in `features.json` and `changes.json` with the completed component drafts. For each important omission, either update the notes or record the editorial reason in the corresponding `features.json` entry's `score_reason`, adjusting its score if the review changes the assessment. Do not treat a PR's presence in `changes.json` as a requirement to give it a release-note section; apply the reader-centric rubric. ## Core review questions Use the shared rubric from [`../editorial-scoring/SKILL.md`](../editorial-scoring/SKILL.md) rather than inventing a new one here. In particular: - keep the same reader-centric `10 / 8 / 6 / 4 / 2 / 0` scale - apply the same 80/20 audience filter - compare the draft against the examples to see whether it still teaches instead of merely enumerating ### Example check Compare the draft against the component examples: - Does the length match the importance? - Are medium-value items grouped instead of getting their own heavyweight sections? - Are performance stories backed by evidence? - Does the draft teach, not just enumerate? ## Common failure modes - **Over-scoring** — too many `4-6` items are promoted to top-level sections - **Under-explaining** — a real `8+` feature is present but buried or not framed clearly - **API inventory mode** — the draft starts mirroring `api-diff` instead of telling a user story - **Technical novelty bias** — clever implementation details outrank practical user value - **Missed revert** — a promoted feature was later backed out or does not appear in the actual build ## Multi-model review pattern For the final editorial QA pass, use this skill as a **two-reviewer parallel check** to get broader viewpoint diversity: Preferred set: 1. **Claude Opus 4.6** 2. **GPT-5.4** Give both reviewers the same inputs and the same requested output: - most correct scoring - most wrong scoring - important omissions - cut list Then synthesize the overlap and disagreements. Treat consensus as a strong signal, but do **not** turn this into a blind vote — fidelity to `changes.json`, the shared `editorial-scoring` rubric, and the repo's editorial rules still wins. ## Reviewer checklist Do not ask reviewers the vague question "do you like this?" Give them the same specific checks instead: 1. **Which headings still sound vague, passive, anthropomorphic, or promotional?** 2. **Which sections fail the 80/20 reader-value test and should be cut, grouped, or demoted?** 3. **Which sentences infer feelings or outcomes (`trust`, `confidence`, `easier`, `better`) instead of stating the concrete change?** 4. **Which sections drift into API-inventory mode instead of teaching a user-facing story?** 5. **Which promoted items were later reverted, backed out, or are missing from the actual build/package set? Cite the revert PR or verification gap.** 6. **Which code samples or examples are weak, confusing, or unsupported by the text?** 7. **Which links, issue/PR references, or formatting details still violate house style?** 8. **What is the single highest-value rewrite still needed in the draft?** 9. **Is the wording conventional, or is it inventing non-standard phrasing or terms?** 10. **Are the subject and its adjective or adverb paired in a familiar way?** 11. **Would this phrasing seem normal in release notes for another developer platform?** 12. **If `release-notes/features.json` lists this feature, does the section begin with the standard preview blockquote?** Ask reviewers to answer with file + heading + issue + suggested rewrite. This produces actionable review instead of general taste feedback. ## Output Return a concise review with: 1. **Most correct scoring** — the features that are best prioritized 2. **Most wrong scoring** — over-scored and under-scored items 3. **Important omissions** — items from `changes.json` / `features.json` that should likely be promoted 4. **Cut list** — what to group, compress, demote, or drop first As a working rule of thumb: - **8+** — section-worthy - **6-7** — grouped paragraph or short section - **0-5** — bug-fix bucket, one-liner, or cut