changelog-audit

Changelog Audit

Audits CHANGELOG.md before a Warp release. Operates in two modes auto-detected from the resolved ref name:

• Release-branch mode (ref name matches ^release-): the upcoming release section is being finalized. Run all cleanup passes, promote [Unreleased] → [X.Y.Z], and bump the compare-link reference block at the bottom.
• Main mode (anything else, including bare main): tidy the live [Unreleased] section in place. If main's CHANGELOG is out of sync with one or more released tags, also back-port the tag's section, dedupe redundant [Unreleased] entries, and rotate the compare-link refs. No rename of [Unreleased].

Cleanup passes (some mode-conditional, run in this order):

• Phase 1.5 (main only, conditional) — Post-release sync. When a stable tag exists whose [X.Y.Z] section is missing from main's CHANGELOG, back-port the section from the tag, dedupe [Unreleased] entries that already shipped, and rotate compare-link refs. Runs unconditionally when triggered (not skippable).
• Phase 2 — Lost-entry recovery. Find entries that landed inside an already-released section due to merge=union and propose moves up.
• Phase 3 — Verify, consolidate, link metadata, and check section placement. Confirm non-trivial entries are accurate against the actual code (run code if needed); merge "Add X / Fix X / Change X" sequences for never-shipped features into a single accurate entry; retro-search GitHub for missing GH refs; and re-classify entries that landed in the wrong subsection (e.g., a behavior change wrongly under Fixed) or are missing a **Breaking:** marker.
• Phase 4 — Impact sort. Within each subsection, most user-impactful first; soft preference for keeping similar entries adjacent.
• Phase 5 — Language pass. Drop entries with no user-facing impact, rewrite jargon-heavy entries, fan out to user-perspective subagents on ambiguous cases, then run the editorial conventions sweep (imperative mood, hyphenation, GH-link position, symbol formatting consistency).
• Phase 6 — Line-wrap and consolidated diff. 120-char hard limit, prefer fewer lines, preserve semantic line breaks where they help raw-text readers.
• Phase 7 (release-branch only) — Promote + ref bump. Rename header and update the link-reference block.

Edits land in CHANGELOG.md directly. All passes stage their changes to an in-memory buffer; nothing is written until Phase 6 surfaces the consolidated diff and the user confirms. Phase 1.5 (post-release sync, on dedupe decisions), Pass 2 (lost-entry recovery), Pass 3 (consolidations and retro-GH ref insertions), and Pass 5 (rewrites and deletions) prompt before staging certain decisions so the user can decide on a per-candidate basis. Phase 7 (release-branch only) confirms its rename + ref-bump diff separately and writes after that confirmation.

Inputs:

• [ref] (positional argument, optional). Any git ref. If omitted, defaults to HEAD. The skill never assumes the current working tree's branch matches what the user intends to audit; the ref is the source of truth for content reads.

Reference files (loaded on demand via Read):

• references/sorting-rubric.md — Phase 4 impact-ordering rules with worked examples.
• references/language-conventions.md — Phase 5 conventions: what belongs in CHANGELOG, what doesn't, internal-jargon flag list, user-perspective subagent prompt template.

Phase 1 — Resolve scope

1. Parse the ref argument. If empty, treat as HEAD.

2. Determine mode from the ref. Resolve the ref to a name, then strip any remote prefix:

   resolved=$(git rev-parse --verify --abbrev-ref --symbolic-full-name <ref> 2>/dev/null \
              || git rev-parse --verify --abbrev-ref --symbolic-full-name origin/<ref> 2>/dev/null \
              || git rev-parse --verify --abbrev-ref --symbolic-full-name upstream/<ref> 2>/dev/null)
   short=${resolved#origin/}; short=${short#upstream/}
   

   If $short matches ^release- (e.g., release-1.13, release-1.13.4) → release-branch mode. Otherwise → main mode.

   Edge case: ref is a tag like v1.13.0rc1. Treat as release-branch mode if the tag's commit is reachable from a release-* branch (git branch -r --contains <tag>); else main mode. When in doubt, ask.

3. Determine target version:

   • Read VERSION.md and warp/config.py at the resolved ref via git show <ref>:VERSION.md and git show <ref>:warp/config.py. Take the first that parses to a MAJOR.MINOR.PATCH (strip dev0, rc1, .dev0, etc.). VERSION.md wins on conflict.
   • In release-branch mode the version must parse to a clean X.Y.Z. If it doesn't, surface the raw string and ask the user.
   • In main mode the version drives nothing (no rename), but record it for the report header.

4. Determine base release tag for the lost-entry diff. Use the parsed (major, minor) from step 3 to restrict the tag pattern; do not just take the highest tag merged into the ref (an rc of the same minor would land first).

   # Release-branch mode: previous minor (X.Y-1).*. Use integer math on the parsed version.
   git tag --merged <ref> --list 'v<major>.<minor-1>.*' --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1
   
   # Main mode (or fallback): highest clean stable tag overall.
   git tag --list 'v*' --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1
   

   Filter excludes anything with rc, dev, beta, or other suffixes. Take the first result.

   Major-boundary fallback: if minor == 0 (e.g., target (2, 0)), there is no v2.-1.* line. Enumerate from the previous major instead: git tag --merged <ref> --list 'v<major-1>.*' and take the highest. For example, target (2, 0) → pattern v1.* → take the highest stable v1.x.y tag from the result. Always use integer math on the parsed (major, minor) tuple; never treat the dotted version string as a float.

   • In release-branch mode, the result is typically the last release of the previous minor (e.g., release-1.13 → v1.12.1).
   • In main mode, the result is the last stable release overall.
   • If no tag exists, skip Phase 2 and note in the report.

5. Locate the working directory for edits:

   • If git -C <cwd> rev-parse HEAD resolves to the same commit as git rev-parse <ref>, edit in place.
   • Otherwise run git worktree list and check whether <ref> is checked out in a sibling worktree. If so, tell the user the path and ask whether to cd there or create a fresh worktree.
   • If neither, propose git worktree add ../warp-changelog-audit-<ref-slug> <ref> and wait for confirmation. Compute <ref-slug> by replacing every / and any non-[A-Za-z0-9._-] character in the ref with - (e.g., origin/release-1.13 → origin-release-1.13).

6. Detect post-release sync need (main mode only). Get the list of stable tags merged into <ref>:

   git tag --merged <ref> --list 'v*' --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$'
   

   For each tag, check whether ^## \[X.Y.Z\]( - .*)?$ appears in main's CHANGELOG.md (read at <ref>). The set of tags whose header is absent is the missing-tags set. If non-empty, Phase 1.5 will run; surface the set in the confirmation below.

   In release-branch mode, skip this check entirely.

7. Present scope and wait for explicit user confirmation before any mutation:

   Auditing CHANGELOG.md at <ref> in <working-dir>.
   Mode: <release-branch|main>.
   Target version: <X.Y.Z> (source: <VERSION.md|warp/config.py|user>).
   Base for lost-entry diff: <vX.Y-prev.Z> (or: no tag, skipping Phase 2).
   Post-release sync needed: <vX.Y.Z, vX.Y.Z+1, ...>   (main mode only; omit line if missing-tags set is empty)
   Release date placeholder: <YYYY-?? | YYYY-MM-DD>   (release-branch mode only; default `YYYY-??`)
   Confirm to proceed, or override release date.
   

   Mandatory pause. The release-date line is omitted in main mode (no rename happens). The post-release-sync line is omitted in release-branch mode and in main mode when the missing-tags set is empty.

Phase 1.5 — Post-release sync (main mode only, conditional)

Skip in release-branch mode. Skip in main mode when the missing-tags set from Phase 1.6 is empty.

When a release branch is cut and tagged (vX.Y.Z), the release-branch audit promotes [Unreleased] → [X.Y.Z] on the release branch. Main's CHANGELOG keeps the same bullets under [Unreleased] until someone back-ports the section. This phase performs that back-port, removes redundant [Unreleased] entries that already shipped, and rotates the compare-link refs.

The sync runs unconditionally when missing tags are detected — the user does not get to skip it. Out-of-sync CHANGELOGs on main are a bug, not a preference. The user is consulted only on (a) the feature-branch name and (b) per-entry duplicate-removal decisions.

Process the missing-tags set oldest-first (sort ascending). Each newly inserted section goes immediately below [Unreleased], so the final file ends up with the most recent release first — same convention as before.

1.5.1 — Branch enforcement (must run before any mutation)

Determine the current branch in the working directory:

git -C <wd> rev-parse --abbrev-ref HEAD

• main, master, or HEAD (detached): the skill MUST switch to a feature branch before mutating CHANGELOG.md. This is required by the user's "never commit to main" guidance (see auto-memory).
• Anything else: the user is already on a feature branch. Re-use it; do not create another.

When a feature branch must be created, propose <user>/sync-changelog-v<newest-missing-tag>:

• <user> defaults to the local-part of git config user.email (everything before the first @). Example: [email protected] → ershi.
• <newest-missing-tag> is the highest version in the missing-tags set (e.g., if 1.13.0 and 1.13.1 are

Content truncated.