description:Use only when the maintainer explicitly asks to update the changelog — then draft the OpenChamber `[Unreleased]` entries (main app and VS Code extension) summarizing changes since the latest git tag.
**Gate: an explicit maintainer request.** The changelog is written once per release, by the maintainer, as a single story. Both `CHANGELOG.md` files stay untouched by fixes, features, PR merges, de-slop follow-ups, and every other task — a change lands without a changelog line, and the maintainer folds it in later. Proceed past this point only when the current message asks to update the changelog; otherwise stop and leave both files as they are.
Read recent release sections for style. Determine the latest tag (or initial commit fallback), then inspect every commit and changed path through `HEAD`:
A squashed merge commit often collapses a whole PR into a single terse subject line that omits valuable detail. When a commit looks like a squashed PR merge (subject ending in `(#123)`, or a `Merge pull request #123` commit), inspect the PR itself — its title and description usually carry the real user-facing context.
- Prefer the PR description over the squashed commit subject when the description explains the user-visible change more accurately.
- Do not copy PR descriptions verbatim; distill them into the changelog style below.
- Use PR author/metadata to attribute contributor credit (see Contributor Credit).
- If `gh` is unavailable or the PR cannot be fetched, fall back to the commit message and diff, and note any uncertainty rather than inventing details.
## Writing Style
- Match the tone and level of detail of the existing changelog.
- Write like release notes for real users, not marketing. Be concrete and plain-spoken.
- Avoid generic payoff clauses ("making X faster", "improving reliability", "for a smoother workflow", "so you can...") unless the diff clearly proves that exact user-visible outcome.
- Prefer short direct bullets: what changed, where users see it, and only one obvious consequence.
- Omit internal implementation details; do not replace them with vague benefits. If a technical change has no user-visible effect, omit it or group under a plain reliability bullet.
- Avoid internal component names unless users see them (ex: "VS Code extension", "Desktop app", "Web app").
- Use area prefixes in the main changelog when they help grouping (e.g., "Chat:", "VSCode:", "Settings:", "Git:", "Terminal:", "Mobile:", "UI:").
- Do not include commit hashes, file paths, or implementation notes in changelog text.
- Do not mention low-level mechanics ("local refs first", "source of truth", "route", "store", "cache", "payload", "ref resolution"). Translate only when there is a clear user-facing symptom.
- Avoid LinkedIn-style language. Bad: "commit review is faster and branch history is more reliable." Better: "commit history can now show file diffs inline."
## Highlights and Ordering
- Sort bullets by user impact, not commit order. Breaking changes first, then significant new capabilities or broad user-visible improvements, then smaller features, fixes, and visual polish.
- Keep the opening highlight block contiguous. Place every bold highlight before the first regular bullet; a regular bullet marks the end of the highlight block.
- Mark only the strongest highlights with a bold area prefix, such as `- **Chat attachments:** ...`. Usually the first 1–3 bullets; fewer when the release lacks substantial changes, more only when clearly justified.
- Treat a change as a highlight only when it introduces a substantial user-facing capability, materially changes a common workflow, or fixes a severe/widespread problem. Do not bold merely because a bullet is first, has a large diff, or was hard to implement.
- Keep related platform bullets together only when that does not push a more important change too far down.
- Rank highlights independently in each changelog. A main-app highlight is not automatically a VS Code highlight.
## VS Code Changelog Rules
- Craft entries only for behavior present in the VS Code extension. Exclude Desktop, Web, Mobile/PWA, and main-app-only UI.
- **Reachability check before every entry.** A change touching shared UI or the VS Code bridge earns a VS Code changelog entry only when the surface is actually mounted from the VS Code entrypoint (`packages/vscode/webview/main.tsx` → `VSCodeApp` → `VSCodeLayout` — which mounts only a subset of shared surfaces; consult the surface map in `packages/vscode/src/DOCUMENTATION.md` when present, trace the mount when not). Shared code that VS Code never mounts is dead there — an entry for it is a false claim users will file bugs about. When in doubt, leave the entry out of the VS Code changelog.
- For every bullet: "Could a user point to this in the UI or behavior?" If not, rewrite or drop it.
- For every VS Code bullet: verify the change applies to the extension, not just shared web UI or server code.
- For every bold bullet: "Would a user reasonably call this a headline change?" If not, unbold or move it lower.
- Read the finished list top to bottom; confirm each bullet is no more important than those above it, except where keeping related platform bullets together improves readability.
- Do not bundle unrelated changes to reduce bullet count. Prefer omitting minor internal fixes over vague catch-all sentences.
- Mention mostly-internal refactors only when there is a concrete user-visible fix; otherwise add no bullet.
The lists are complete when every bullet is supported by inspected evidence, points to user-observable behavior, is ranked by impact, appears only in changelogs whose runtime receives it, and credits eligible contributors.
