spec: Add PRD for release notes drafter agent

[amikofalvy]

Summary

Proposes a Claude-powered release notes generator that integrates with changesets to produce polished, user-friendly release notes.

Core insight: Changesets handles the tracking of changes perfectly. Claude handles the communication of changes to users.

Key Features

• Generate polished release notes in the Version Packages PR (reviewable before merge!)
• Highlight breaking changes with migration guides
• Maintain existing changeset workflow (no changes for developers)
• Graceful fallback if Claude API fails

Workshop Topics

The PRD includes several open questions for discussion:

• Where should release notes live in the PR?
• How much context should Claude receive?
• What sections should be included?
• How to integrate with changesets/action?

Files Changed

• spec/release-notes-drafter.md - Full PRD with technical approach and implementation phases

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agents-api	Ready	Preview, Comment	Feb 5, 2026 9:33am
agents-docs	Ready	Preview, Comment	Feb 5, 2026 9:33am
agents-manage-ui	Ready	Preview, Comment	Feb 5, 2026 9:33am

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0476810

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[claude]

Claude finished @amikofalvy's task in 2m 59s —— View job

---

PR Review Summary

3 Key Findings | Risk: Low

This is a well-structured PRD for a release notes drafter that addresses a real pain point. The proposal is technically feasible and builds on existing experimental infrastructure. My feedback focuses on improving the document's structure and resolving ambiguities before implementation begins.

---

🟠🔶⚠️ Major (2) 🟠🔶⚠️

🟠 1) spec/release-notes-drafter.md Document exceeds spec authoring guidelines

Issue: The PRD is ~2,419 words, significantly exceeding the 500-1,500 word target defined in spec/spec-authoring.md. Additionally, spec documents are intended for "living reference documents that summarize architecture, decisions, and implementation patterns" of existing features, not proposals for future work.

Why: This creates a mismatch in document purpose. The spec/ directory is for AI agent context about implemented features, not PRDs. This could confuse AI agents about what actually exists vs what's proposed, and may cause issues when the feature is implemented (the PRD becomes outdated).

Fix: Consider one of these approaches:

1. Move to a different location: Create a proposals/ or rfcs/ directory for pre-implementation documents
2. Transform post-implementation: Keep the PRD during development, but replace it with a concise spec (500-1500 words) once the feature ships
3. Split the document: Extract the "System Prompt Design" and "Implementation Details" sections into separate, focused docs

---

🟠 2) spec/release-notes-drafter.md:364-476 Success metrics duplicated with divergent formatting

Issue: Success metrics appear twice in the document - once at lines 364-371 and again at lines 467-475. The second occurrence adds a "How to Measure" column not present in the first.

Why: Duplicated content increases maintenance burden and creates ambiguity about which is authoritative. The "How to Measure" column in the second instance is valuable and should be the canonical version.

Fix: Remove the first occurrence (lines 364-371) and keep only the more detailed version at lines 467-475 with the "How to Measure" column.

---

📌 Point-fix Edits (0)

No inline suggestions posted — this is a documentation PR where broader structural feedback is more appropriate than line-level fixes.

---

Final Recommendation

💡 APPROVE WITH SUGGESTIONS

Summary: This is a thoughtful, well-researched PRD that addresses a real pain point (15-30 min manual release note curation). The technical approach is sound, building on existing experimental infrastructure in release.yml.

The main suggestions are structural: (1) consider whether spec/ is the right home for pre-implementation proposals, and (2) consolidate the duplicated success metrics. The open questions (Q1-Q7) are appropriately flagged as workshop topics and don't need resolution in the PRD itself.

The phased implementation approach (MVP → CI → Polish → Agent) is pragmatic, and the fallback strategy ("never block releases") shows good operational thinking. Ready to merge with minor cleanup. 🎉

---

Other Findings (4)

Potentially valid

(minor observations, not blocking)

Location	Issue	Reason Excluded
spec/release-notes-drafter.md:484	Reference to .claude/agents/pr-review.md is outdated (file exists but pattern example could be more current)	Informational - the pattern reference is still accurate
Lines 222-257	Code example missing imports (fs, RELEASE_NOTES_SYSTEM_PROMPT)	Illustrative snippet, not production code
Line 261	Reference to v0.43.0 release structure - should verify this is still the latest/best example	Style guide, implementation will verify

Discarded as not applicable

Location	Issue	Reason Excluded
Open Questions Q1-Q7	Unresolved decisions	Explicitly framed as "workshop topics" - appropriate to defer

---