docs(agents): add release-title rule — name searchable features alongside the benefit - #677
Conversation
…side the benefit Release titles follow the benefit-first voice rule, but a release index is also a scan-and-search surface. When a launch introduces a term people look for (e.g. "Cloud MCP"), the title should carry that name alongside the benefit so the release is legible to scanners and search. Adds a "Release titles" section to principles/releases.md and a cross-link bullet under voice.md "Leading with value". Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
Pull request overview
Adds guidance to the internal agent docs for writing release titles that remain benefit-first while surfacing searchable feature names (e.g., “Cloud MCP”) as a short prefix for scan/search discoverability.
Changes:
- Adds a new “Release titles” principle to the releases guidance.
- Adds a matching cross-link bullet to the voice guidance under “Leading with value”.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
.agents/principles/releases.md |
Introduces a “Release titles” section describing when/how to prefix searchable terms while keeping benefit-focused phrasing. |
.agents/voice.md |
Adds a bullet under “Leading with value” linking to the new release-title guidance. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
cypress-design
 |
||||||||||||||||||||||||||||
| Project |
cypress-design
|
| Branch Review |
ryanjwilke/release-title-feature-name-rule
|
| Run status |
|
| Run duration | 02m 26s |
| Commit |
|
| Committer | Ryan Wilke |
| View all properties for this run ↗︎ | |
| Test results | |
|---|---|
 |
0
|
 |
0
|
 |
0
|
 |
0
|
 |
2
|
| View all changes introduced in this branch ↗︎ | |
Warning
No Report: Something went wrong and we could not generate a report for the Application Quality products.
Address review note that para 1 ("open on the outcome") read as
contradicting para 2 ("lead with the name"). Reframe the prefix as a tag
on the benefit-led phrasing rather than the lead, removing the tension.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
cypress-design
|
||||||||||||||||||||||||||||
| Project |
cypress-design
|
| Branch Review |
main
|
| Run status |
|
| Run duration | 02m 19s |
| Commit |
|
| Committer | Ryan Wilke |
| View all properties for this run ↗︎ | |
| Test results | |
|---|---|
|
|
0
|
|
|
0
|
|
|
0
|
|
|
0
|
|
|
2
|
| View all changes introduced in this branch ↗︎ | |
Warning
No Report: Something went wrong and we could not generate a report for the Application Quality products.
What
Adds a Release titles rule to the design-system agent docs: release titles keep the benefit-first voice rule, but when a launch introduces a term people scan or search for (e.g. "Cloud MCP"), the title carries that name as a short prefix alongside the benefit.
Cloud MCP Beta: Debug failing tests with your AI assistantDebug failing tests with your AI assistant (beta)Why
A release index is also a scan-and-navigate (and for some launches, search-and-discovery) surface. A benefit-only title can leave someone scanning the list unsure what actually shipped, and feature/category names aren't always self-explanatory on their own (e.g. "Smart Orchestration"). Engineers scanning the releases page for "MCP" couldn't tell we'd shipped it — the trigger for this rule.
Changes
.agents/principles/releases.md— new## Release titlessection (3 principles: lead-with-benefit-but-name-it, prefix the searchable term, don't force a name into every title)..agents/voice.md— cross-link bullet under "Leading with value".Scoped deliberately: applies only when the term carries recognition/SEO weight people actually search for, not every release.
🤖 Generated with Claude Code
Note
Low Risk
Documentation-only updates to internal agent guidance; no runtime, security, or customer-facing product behavior changes.
Overview
Adds agent documentation for how to write release titles on the releases index: keep benefit-first voice, but when a launch introduces a searchable product or feature name (e.g. Cloud MCP), use a short name prefix + benefit pattern such as
Cloud MCP Beta: Debug failing tests with your AI assistantinstead of burying the name or stage at the end.A new Release titles section in
releases.mdspells out three rules (benefit plus discoverability, prefix recognizable terms, don’t force names on every release).voice.mdgains a matching bullet under Leading with value with a cross-link back to that section.Reviewed by Cursor Bugbot for commit ee44ea9. Bugbot is set up for automated code reviews on this repo. Configure here.