release-notes

Required inputs — ask once for both, then start: starting point (commit SHA, tag, version, or branch) and target file. Optional: end point (default HEAD), version label, audience hint.

Phase 2 — Triage (synthesis, no tool calls)

One logical change = one entry, however many commits or files. Discard noise: merges, version bumps, formatting-only, lockfile churn, CI tweaks (unless full coverage was asked). Buckets:

• ADDED — new capability, command, flag, endpoint, config, format
• CHANGED — modified behavior of an existing capability
• FIXED — bug fix with a user-observable symptom
• DEPRECATED — still works, scheduled for removal
• REMOVED — gone (breaking)
• PERFORMANCE — measurable speed / memory / latency change
• SECURITY — auth, permissions, validation, sandboxing
• INTERNAL — refactor, build, infra (omitted unless asked)

Phase 3 — Verify each entry (parallel across entries)

The hunk is a hint; the file on disk is truth. Per entry:

• view_signatures on touched files, then view the changed function / type / config as it stands now
• structural_search — every concrete reference exists EXACTLY as you'll name it (flag spelling, env var, config key, endpoint path, public symbol)
• semantic_search — "X now does Y" traces to code that observably does Y
• graphrag(operation=search) — user-visible reach of cross-cutting changes Keep an evidence record per entry (discarded from the notes): file:line in current state, exact name as it now exists, old behavior (only if confirmable from a prior commit or a removal/rename), new behavior in user-observable terms. Can't state the new behavior that way with evidence → drop the entry. Two plausible readings → the better-evidenced one; tied → omit.

Phase 4 — Write (one text_editor or batch_edit call)

Compose per output_format. File missing → create it with this release as the first section. File exists → PREPEND the new section (newest on top); never rewrite older sections.

Phase 5 — Validate

Re-read the file; confirm every concrete reference (flag, command, path, config key, version, endpoint) via structural_search or the manifest. Mismatch → fix or remove.

After delivery, memorize() project-specific naming or grouping conventions (importance 0.6–0.8).

## <Version or Date> — <one-phrase headline>

<Optional 1–3 sentence overview if the release has a unifying theme. Skip if it is a grab-bag.>

### Breaking changes
- <Only when something breaks: what stops working, who is affected, and the exact upgrade action. Listed first because readers must act on it; the same change still appears once in its bucket below, briefly.>

### Added
- <1–4 sentences. Names the user-facing thing; what it does and when to use it.>

### Changed
- <Behavioral change in user-observable terms. If subtly breaking, the migration path in one sentence.>

### Fixed
- <The user-visible symptom that no longer happens; internal cause only if it helps users tell whether they were affected.>

### Deprecated
- <What is deprecated, its replacement, and the removal timeline if known.>

### Removed
- <Breaking removal. Name the prior thing exactly so users can grep their own code.>

### Performance
- <Measurable change. Numbers only from the code or commit body — never invented benchmarks.>

### Security
- <What was hardened, in terms of what the fix prevents; no exploit details.>

Fixed bucket order as above; omit empty buckets; INTERNAL only if asked.

Closing line in the conversation (not the file), nothing else: Wrote <N> entries across <K> buckets to <path>. Validated <M> concrete references. Empty range → write nothing; reply No user-facing changes in <start>..<end>. <K> commits scanned (internal only).

Stop and ask when:

• A ref doesn't resolve.
• The target already has the same version header → overwrite, prepend a new section, or pick another label?
• A breaking change has no migration path in code or commit context → ask for the guidance to include.
• The range is >80% INTERNAL → confirm before writing a sparse release.

Scope and output

• Write only the user's target file, in one text_editor or batch_edit call; no staging or scratch files. Never edit older release sections.
• No commit SHAs, PR links, internal file paths, internal churn (unless asked), TL;DR, footer, or "see also" — the notes stand alone.
• After writing, one closing line in the conversation. Nothing else.