update-changelog

name: update-changelog description: Create or update a local CHANGELOG.md version entry with concise, high-signal release notes; ask for the target version when it is not provided or discoverable. summary: Create or update concise local changelog release notes.

Update Changelog

Use this skill when creating, refreshing, or simplifying a version entry in the local CHANGELOG.md file.

Goal

Produce concise, high-signal release notes for one target version. The entry should explain user-facing, operator-facing, or release-relevant impact, not list implementation steps.

Version handling

1. Determine the target version before editing:
   • Use a version explicitly provided by the user.
   • If the user asks to update an existing release and only one relevant version section is obvious from context, use that version.
   • Otherwise ask the user for the target version before editing CHANGELOG.md.
2. Never invent a version number.
3. If CHANGELOG.md already has ## [<version>] - <date-or-status>, update that section only.
4. If the version section does not exist, create a new dated section near the top, after the changelog title/introduction and before older versions.

Release date handling

1. Use TestPyPI release history as the authoritative source for published reflex-reviewer release dates:
   • Page: https://test.pypi.org/project/reflex-reviewer/#history
   • JSON fallback: https://test.pypi.org/pypi/reflex-reviewer/json
2. For published releases, use the ISO calendar date from release history.
3. If using the JSON fallback, derive the release date from the earliest uploaded distribution timestamp for the target version.
4. If release history has no entry for the target version, treat the version as unpublished:
   • use Unreleased when the entry represents pending release notes,
   • ask for the intended release date before using an ISO date,
   • leave the date/status off only if the user explicitly requests an undated heading.

Use this version header format for published releases:

## [<version>] - YYYY-MM-DD

Use this version header format for unpublished pending releases:

## [<version>] - Unreleased

Source material

Gather only enough context to write accurate release notes:

• Existing CHANGELOG.md structure and tone.
• TestPyPI release history for the target version date when the release is published.
• Staged changes first; if nothing is staged, use unstaged changes.
• Relevant commits, project memory, or user-provided notes when they clarify release intent.
• Nearby docs/config only when needed to understand user-visible impact.

Required categories

Use standard Keep a Changelog-style categories in this order:

1. ### Added
2. ### Changed
3. ### Fixed

Use optional categories only when clearly relevant:

4. ### Deprecated
5. ### Removed
6. ### Security

Skip empty headings.

Writing rules

• Keep the entry concise: usually 5-12 bullets total for a normal release.
• Prefer one high-signal bullet over several low-level bullets about the same change.
• Lead with product, runtime, configuration, or operational impact.
• Mention config keys, commands, modules, or APIs only when they help users understand the release.
• Avoid implementation logs, test-only bullets, generic documentation bullets, and internal refactor detail unless it materially changes release behavior.
• Avoid duplicate ideas across categories.
• Do not include raw prompt bodies, diffs, secrets, credentials, tokens, or sensitive payload data.
• Keep initial/foundational releases under ### Core capabilities only when the user explicitly requests that exception.

Category guidance

Added

Use for newly available capabilities, workflows, configuration controls, integrations, or supported behavior.

Changed

Use for behavior changes, runtime orchestration changes, configuration semantics, operational defaults, or meaningful architecture changes that affect maintainability or operation.

Fixed

Use for bug fixes that materially affect correctness, release safety, review reliability, data integrity, posting behavior, parsing, or runtime stability.

Deprecated

Use only when a feature, configuration key, command, or behavior remains available but is explicitly planned for future removal.

Removed

Use only when a feature, command, configuration key, compatibility path, or file/module surface has been removed.

Security

Use only for vulnerability fixes, credential-handling improvements, sensitive-data logging fixes, or security-relevant behavior changes.

Workflow

1. Read CHANGELOG.md.
2. Resolve the target version using the version-handling rules above.
3. Resolve the release date or Unreleased status using the release-date handling rules above.
4. Inspect the relevant git diff or commits.
5. Draft concise release-note bullets grouped by category.
6. Remove weak, duplicate, overly specific, or test-only bullets.
7. Create or update only the target version section.
8. Verify the section is ordered correctly, has no empty headings, and contains only concise, high-signal release notes.

Output template

Use this template, omitting empty categories:

## [<version>] - YYYY-MM-DD

### Added
- <new capability or supported behavior>

### Changed
- <behavior, configuration, runtime, or operational change>

### Fixed
- <correctness, reliability, parsing, posting, or data-integrity fix>

Completion checklist

• Target version was provided, clearly inferred from context, or requested from the user before editing.
• Published release dates were verified from TestPyPI release history, or unpublished entries are marked Unreleased.
• The target section was created or updated, and unrelated versions were left alone.
• Empty headings were skipped.
• Bullets are concise, high signal, and release-note oriented.
• No sensitive content or raw implementation payloads were included.