---
requires: LF_RELEASE_NOTES_CONTEXT env var pointing to JSON release context
produces: RELEASE_NOTES.md
diff_files: false
---
Write release notes that fuse release intent with shipped behavior.
## Workflow
1. Read `LF_RELEASE_NOTES_CONTEXT` and parse the JSON.
2. Treat `decisions` as the intent ledger: what changed in product direction, release policy, operations, and user experience during this cycle.
3. Treat `merged_prs` and, when needed, `git diff <prev_tag>..HEAD`, as the behavior ledger: what actually shipped.
4. Fuse them. The release notes should explain what users, operators, and contributors can do differently now. Use commits/PRs to ground every claim.
5. Keep the previous release-note voice if `previous_release_notes` exists, but improve structure when the previous notes were too raw.
6. Write `RELEASE_NOTES.md`.
## Output
Raw markdown only. No JSON. No code fence wrapping the output.
First line must be exactly:
```markdown
# v<version>
```
Structure:
1. **Opening story** — 2-4 sentences. Answer “why upgrade?” and name the through-line of the release. This is narrative, not a list.
2. **Thematic sections** — sections named after user/operator outcomes, not implementation buckets. Each section starts with a short paragraph connecting the decisions to the shipped behavior, followed by concise bullets for scanners.
3. **Operational notes** — include only when relevant: release process, deployment, migration, billing, TestFlight, compatibility, or known manual steps.
4. **Small changes** — minor fixes and polish that do not deserve a full theme.
## Source handling
- Decisions are source material, not release notes. Do not paste the ledger wholesale.
- PR titles are source material, not release notes. Do not dump them chronologically.
- If decisions and commits disagree, trust the commits for what shipped and use decisions to explain why.
- If decisions mention future work that did not ship, either omit it or mark it clearly as “not included.”
- If there are no decisions, build the narrative from merged PRs and diffs.
- If there are decisions but no matching shipped behavior, keep the note cautious: describe the policy/intent change, not an implementation that is absent.
## Style
- Lead with outcomes, not mechanisms.
- Be specific and factual. No marketing filler.
- Prefer a few strong themes over many headings.
- Write for the person deciding whether to upgrade and the operator debugging the release six weeks later.
- Synthesize from the merged PRs and their intent; `RELEASE_NOTES.md` is the interpreted story, not a changelog.
## Quality bar
A good release note could not be generated from PR titles alone. It reads the intent from the merged PRs (their descriptions, not just titles), proves it against shipped changes, and leaves a concise operational record. Per-decision context lives in each wave's `MEMORY.md`, not a central ledger.