bntvllnt · bntvllnt · Apr 17, 2026 · Apr 17, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,11 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.13.3] - 2026-04-17
+
+- feat(github): add release-title prerequisites and preview-aware release strategy guidance
+- feat(oss-readiness): add OSS release messaging rubric for titles and opening summaries
+
 ## [1.13.2] - 2026-04-17
 
 - feat(workflow): load rules-discovery across plan, ship, fix, focus, and spec-review

diff --git a/github/README.md b/github/README.md
@@ -11,6 +11,7 @@ GitHub skill using GitHub CLI (`gh`): repos, issues, pull requests, Actions, rel
 - PRs: `github/references/pr.md`
 - Actions: `github/references/actions.md`
 - Releases: `github/references/release.md`
+- Release strategy + naming + preview guidance: `github/references/release-strategy.md`
 - Advanced API: `github/references/api.md`
 
 Release deep dives:
@@ -19,6 +20,8 @@ Release deep dives:
 - Manage: `github/references/release-manage.md`
 - Assets: `github/references/release-assets.md`
 
+Use `github/references/release-strategy.md` for title quality, dominant-change selection, release-note opening lines, and GitHub preview / OG-image considerations.
+
 ## Requirements
 
 - `gh` (GitHub CLI)

diff --git a/github/references/release-strategy.md b/github/references/release-strategy.md
@@ -18,21 +18,57 @@ Rules:
 - Use `--verify-tag` on every `gh release create`
 - Never skip versions
 
+## Release Title Prerequisites (ENFORCED)
+
+Before writing a release title, confirm all of these:
+
+- **Stable scope**: the merged diff is settled; do not title from an outdated PR description
+- **Dominant change identified**: pick the main user-facing change, not the most recent internal task
+- **Audience identified**: know whether the release is mainly for users, contributors, or operators
+- **Title/body alignment**: the first lines of the release notes reinforce the same story as the title
+- **Truthfulness**: the title is strong but not inflated beyond what the release actually changed
+- **Social-card awareness**: assume the title and opening lines may appear alone on GitHub release cards or preview images
+
 ## Release Title Format (ENFORCED)
 
 ```
 vX.Y.Z — {Short Description}
 ```
 
 Examples:
-- `v1.0.0 — Analyze Skill`
-- `v1.2.0 — GitHub Skill + Git Docs Expansion`
+- `v1.0.0 — Analyze skill`
+- `v1.13.1 — Code review, supercharged`
+- `v1.14.0 — Portable review specs`
+
+Weak examples:
 - `v1.3.1 — GitHub PR Workflow Improvements`
+- `v1.3.1 — Updates`
+- `v1.3.1 — Misc fixes`
 
 Rules:
 - Use em dash `—` (not `-` or `–`)
 - Title ≤ 70 characters
-- Describe WHAT was added/changed, not HOW
+- Lead with the dominant outcome, not the implementation detail
+- Be specific enough that the reader can infer what changed in one glance
+- Prefer user-facing capability over internal process wording
+- Avoid filler like `updates`, `improvements`, `misc`, `cleanup`, `refactors`
+- If two candidates exist, choose the one that better survives being seen without context on a release card
+
+Practical title heuristic:
+
+```text
+vX.Y.Z — {specific outcome}
+```
+
+Good:
+- `v1.13.1 — Code review, supercharged`
+- `v0.8.0 — Faster local inference`
+- `v2.4.0 — Rules discovery everywhere`
+
+Bad:
+- `v1.13.1 — Workflow changes`
+- `v0.8.0 — Performance updates`
+- `v2.4.0 — Internal improvements`
 
 ## Release Description Format (ENFORCED)
 
@@ -78,6 +114,22 @@ Every release description MUST follow this exact structure:
 - Every file listed must have a specific, meaningful description
 - Group related changes when describing (e.g., "Updated routing table, references section, and output template links")
 
+### Opening Lines / Preview Rules
+
+Assume the release title plus the opening summary / first bullets may be the only text visible in:
+
+- GitHub release cards
+- Open Graph preview images
+- link unfurls in chat tools
+- social post screenshots
+
+Therefore:
+
+- The opening summary must reinforce the title immediately
+- The first bullet should restate the dominant change in concrete terms
+- Do not lead with internal maintenance work if the release is mainly about a user-facing capability
+- Do not bury the dominant change below less important items
+
 ### Changed Files Detail Level by Bump
 
 | Bump | Detail Level |
@@ -119,7 +171,10 @@ Follow the enforced format above. No shortcuts.
 Before publishing, check:
 
 - [ ] Title follows `vX.Y.Z — {Description}` format
+- [ ] Title is specific, outcome-first, and brief
+- [ ] Title matches the dominant user-facing change in the merged diff
 - [ ] Summary paragraph is present and specific
+- [ ] Opening lines reinforce the same story as the title
 - [ ] Every new file is listed with description
 - [ ] Every changed file is listed with specific change details
 - [ ] No vague descriptions ("minor updates", "various fixes")

diff --git a/github/references/release.md b/github/references/release.md
@@ -2,11 +2,11 @@
 
 Use this section as the entry point for release operations.
 
-**MANDATORY: Read `release-strategy.md` before creating or editing any release.** It defines versioning rules, title format, description format, and the generation protocol.
+**MANDATORY: Read `release-strategy.md` before creating or editing any release.** It defines versioning rules, title format, dominant-change selection, description format, preview/OG-card guidance, and the generation protocol.
 
 | Intent | Reference |
 |---|---|
-| **strategy / format / versioning** | **`release-strategy.md`** |
+| **strategy / format / versioning / title quality / previews** | **`release-strategy.md`** |
 | create / publish release | `release-create.md` |
 | list / view / edit / delete release | `release-manage.md` |
 | upload / download assets, verify attestations | `release-assets.md` |

diff --git a/oss-readiness/README.md b/oss-readiness/README.md
@@ -23,6 +23,7 @@ Use natural language or slash-command shorthand:
 - `generate llms.txt`
 - `bump stale version refs in docs`
 - `check OSS CI readiness`
+- `audit release messaging`
 - `/oss`
 - `/oss fix`
 - `/oss llms`
@@ -36,6 +37,7 @@ Use natural language or slash-command shorthand:
 - Repo hygiene: `.gitignore`, changelog, issue/PR templates, topics, description
 - CI checks: test/lint coverage, optional publish workflow for libraries
 - Agent instructions: canonical `AGENTS.md` plus optional harness-specific aliases
+- Release messaging: title quality, dominant-change selection, and opening-summary quality for public release notes or announcements
 
 ## Portability
 
@@ -53,6 +55,7 @@ This skill is designed to work across agent harnesses:
 - LLM docs generation: `oss-readiness/references/llms-generation.md`
 - Version sync: `oss-readiness/references/version-sync.md`
 - CI validation: `oss-readiness/references/ci-validation.md`
+- Release messaging: `oss-readiness/references/release-messaging.md`
 - Scaffold templates: `oss-readiness/templates/`
 
 ## Requirements

diff --git a/oss-readiness/SKILL.md b/oss-readiness/SKILL.md
@@ -4,7 +4,8 @@ description: |
   Open-source/public release readiness gate. Audit repos for OSS basics, scaffold missing public-release files,
   generate llms.txt + llms-full.txt, validate CI, and sync version references.
   Triggers: "oss", "/oss", "open source readiness", "release readiness", "public release",
-  "go public", "oss audit", "llms.txt", "generate llms", "version bump docs", "scaffold OSS files".
+  "go public", "oss audit", "llms.txt", "generate llms", "version bump docs", "scaffold OSS files",
+  "release title", "release messaging", "release notes", "announcement quality".
 compatibility: Agent Skills spec (agentskills.io). Works with any agent product that supports SKILL.md frontmatter + Markdown. Optional CLI helpers: git, gh, grep, find, jq, node or python.
 metadata:
   version: "0.2"
@@ -48,6 +49,7 @@ Use either natural language or shorthand. Route both to the same workflow.
 | Generate LLM docs | `generate llms.txt`, `/oss llms` | `references/llms-generation.md` |
 | Sync version refs | `bump stale version refs in docs`, `/oss bump` | `references/version-sync.md` |
 | Validate CI | `check OSS CI readiness`, `/oss ci` | `references/ci-validation.md` |
+| Review release title / notes / announcement framing | `audit release messaging`, `is this a good OSS release title?` | `references/release-messaging.md` |
 
 ## Template Variables
 
@@ -211,6 +213,7 @@ Any blocking failure caps grade at C maximum.
 - [LLMs Generation](references/llms-generation.md) — `llms.txt` + `llms-full.txt` algorithm
 - [Version Sync](references/version-sync.md) — version detection + doc bumping
 - [CI Validation](references/ci-validation.md) — CI pipeline rules + starter workflows
+- [Release Messaging](references/release-messaging.md) — title, opening-summary, and announcement-quality rubric for public OSS releases
 
 ## Templates
 

diff --git a/oss-readiness/references/checklist.md b/oss-readiness/references/checklist.md
@@ -10,6 +10,40 @@ Scaffolded files must stay portable:
 - Do not hardcode maintainer links, social handles, org names, or inboxes from this skill repository.
 - Prefer an explicitly provided private security channel. If none exists, leave a placeholder and flag it for maintainer input.
 
+## Optional Release Messaging Checks
+
+Run these when there is a concrete release draft, release tag, or announcement draft to evaluate.
+
+These checks are advisory and **not** part of the 23-item OSS basics score unless the user explicitly asks for release-messaging review.
+
+### 24. Release Title Matches the Dominant Change
+- Detection: inspect the latest draft release / release notes / announcement headline
+- Pass:
+  - title is specific
+  - title is outcome-first
+  - title is brief
+  - title reflects the dominant user-facing change
+  - title is truthful, not inflated
+- Fail examples:
+  - `Updates`
+  - `Workflow improvements`
+  - `Internal fixes`
+- Fix: rewrite the title around the main external outcome, not the most recent internal task
+
+### 25. Opening Summary Reinforces the Title
+- Detection: inspect the first 1-3 sentences or first bullets of the release notes / announcement
+- Pass:
+  - opening lines reinforce the same story as the title
+  - the dominant change appears immediately
+  - vague filler does not lead the announcement
+  - opening lines are legible out of context in link previews or screenshots
+- Fail examples:
+  - title says `Faster local inference` but opening lines lead with dependency upgrades
+  - title says `Code review, supercharged` but opening lines lead with generic workflow cleanup
+- Fix: reorder and rewrite the opening summary so the dominant change is visible first
+
+Use `references/release-messaging.md` for the cross-platform rubric.
+
 ## BLOCKING Items (12)
 
 For each item, provide: detection command, pass/fail criteria, and fix action.

diff --git a/oss-readiness/references/release-messaging.md b/oss-readiness/references/release-messaging.md
@@ -0,0 +1,102 @@
+# Release Messaging
+
+Cross-platform rubric for evaluating OSS release titles, release-note openings, and launch-announcement framing.
+
+Use this when the user asks things like:
+
+- `is this a good OSS release title?`
+- `audit release messaging`
+- `improve the release title`
+- `rewrite the opening release notes`
+- `does this announcement read like a real release?`
+
+## Core Principle
+
+The title and opening lines should make the release legible to an outsider in one glance.
+
+That means:
+
+- name the dominant user-facing change
+- say it in plain language
+- avoid internal-only framing
+- avoid hype the diff does not support
+
+## Preconditions
+
+Before writing a title or lead summary, confirm:
+
+1. **Stable scope**
+   - The merged or imminent release diff is known
+2. **Dominant change selected**
+   - One main external change is identified
+3. **Audience selected**
+   - Users, contributors, operators, or developers evaluating the project
+4. **Truthfulness check**
+   - The claim is strong but supported by the release
+
+## Title Rubric
+
+A strong OSS release title is:
+
+- **specific**
+- **outcome-first**
+- **brief**
+- **truthful**
+- **aligned with the dominant change**
+
+Good:
+
+- `v1.13.1 — Code review, supercharged`
+- `v0.8.0 — Faster local inference`
+- `v2.4.0 — Rules discovery everywhere`
+
+Weak:
+
+- `v1.13.1 — Updates`
+- `v0.8.0 — Workflow improvements`
+- `v2.4.0 — Internal cleanup`
+
+## Opening Summary Rubric
+
+The first 1-3 sentences or first bullets should:
+
+- reinforce the same story as the title
+- surface the dominant change immediately
+- avoid leading with maintenance work if the release is really about a feature or capability
+- be understandable when quoted in chat previews or screenshots
+
+Bad pattern:
+
+```text
+v1.13.1 — Code review, supercharged
+
+This release includes several cleanup items, internal refactors, and minor workflow changes...
+```
+
+Better pattern:
+
+```text
+v1.13.1 — Code review, supercharged
+
+This release hardens review in the workflow skill with line-by-line coverage, rule-by-rule enforcement, and fail-closed review output.
+```
+
+## Anti-Patterns
+
+Avoid:
+
+- vague nouns: `updates`, `improvements`, `changes`
+- internal-only framing when the release is externally meaningful
+- hype words with no evidence
+- titles that depend on prior context to make sense
+- opening summaries that bury the real release story under housekeeping
+
+## Fast Evaluation Checklist
+
+- Can a new reader tell what changed from the title alone?
+- Does the title describe the dominant external outcome?
+- Do the opening lines reinforce that same outcome?
+- Would the title still work if shown alone on a social card?
+- Is the wording strong without overselling?
+
+If any answer is no, rewrite before publishing.