Draft product updates from code changes
Turn merged code changes into concise product updates that explain the user-facing features and fixes.
How this works
Turn merged code changes into concise product updates that explain the user-facing features and fixes. Use this to draft understandable product updates from a defined set of code changes. The draft should describe the user-visible result while distinguishing merged work from functionality actually released to the audience.
Gather merged changes for a release window, inspect relevant descriptions and diffs, then verify release and feature-flag state. Group related changes into concise entries with internal evidence links. Engineering and product owners confirm availability and wording before publication.
Before you start
Release scope
Identify the version, date range and target environment.
Change evidence
Obtain merged pull requests, relevant commits and issue context.
Availability evidence
Use deployment records and feature-flag status for the intended audience.
Prepare the inputs
- change_set
- Required
PR ID, merge commit, title, description and diff
Exclude unmerged or reverted changes unless explaining a rollback.
- release_record
- Required
version, deployed commit and environment
A merge timestamp alone does not establish shipping.
- audience
- Required
customer segment and communication format
Avoid internal implementation detail unless it helps users.
- editorial_rules
- Required
entry categories and disclosure constraints
Keep security-sensitive or unreleased details out of public drafts.
Implementation, step by step
Establish the release boundary
- Map the deployed version to included commits and changes.
- Identify reversions and changes behind inactive flags.
Checkpoint: A candidate change list has availability status.
Inspect user impact
- Read descriptions and relevant diffs to identify changed behavior.
- Separate internal maintenance from visible features and fixes.
Checkpoint: Each candidate has an evidence-backed impact statement.
Group related changes
- Combine several PRs that implement one user-facing improvement.
- Avoid counting refactors as new features or omitting a consequential compatibility change.
Checkpoint: The outline contains distinct product outcomes.
Draft entries
- Explain what users can now do or what failure was fixed.
- Use plain language and keep internal source links for reviewer verification.
Checkpoint: The draft matches the intended release audience.
Verify and hand off
- Ask owners to confirm availability, claims and any limitations.
- Save the approved draft in the requested format; publication is a separate authorized action.
Checkpoint: Every entry has a verified release basis.
Decisions along the way
Merged but not deployed
Exclude from shipped notes or label as upcoming only if requested.
Feature is enabled for a subset
State the actual availability or use a targeted draft.
Change has no clear user effect
Keep it in internal notes rather than invent a benefit.
What you will produce
release-notes.md
MarkdownCustomer-oriented release notes awaiting review.
Include: version · features · fixes · known_limits · status
changelog-evidence.csv
CSVA traceability table for each published claim.
Include: entry_id · pr_ids · commit · availability · owner
Check the result
- Confirm every entry is included in the deployed version.
- Check feature flags and audience availability.
- Compare claimed behavior with code and relevant validation evidence.
- Remove internal secrets, customer identifiers and unsupported performance claims.
When something goes wrong
Deployment record unavailable
Keep availability unverified and hold shipped wording.
PR description contradicts the diff
Inspect the implementation and ask the owner to clarify.
Late rollback occurs
Update affected entries and retain the prior draft for history.
A worked example
SYNTHETIC EXAMPLE · NOT A REPORTED BUSINESS RESULT
Request
Synthetic: draft notes for release R6.
Inputs
PR11 adds saved filters and is deployed with its flag enabled. PR12 adds export but its flag is disabled. PR13 refactors logging with no visible change.
Expected result
Synthetic result: include saved filters, omit export from shipped features and keep logging in internal maintenance notes. The evidence table links the entry to PR11 and R6.
Run a small pilot
Start small
Prepare notes for one recent release with known deployed behavior.
Record the baseline
Record editing time and availability corrections.
Agree success criteria
Agree factual accuracy and user clarity criteria before recurring generation.
Stop or revise
Stop publication preparation if deployed commits or feature availability cannot be established.
Keep the scope clear
- Generated notes do not prove deployment or feature availability.
- Do not publish or disclose unreleased implementation details without the authorized scope.
Check before using
Check that features are actually available to users. A merged pull request does not establish that a release has shipped.
Business activities
- Create and publish content
- Build and change software
FROM A RECIPE TO YOUR WORKFLOW
Bring the company context together.
This workflow needs reliable inputs before it needs a better prompt. Moat8 Vault brings working information into a readable archive for the AI tools you use.
For this recipe: Merged pull requests for a period · Product communication style
Start with one recurring task, agree which sources to use, and review the first result with your team.
Discuss this workflow