technical-changelog

Produce a one-page technical report of what changed for a release, stored in docs/technical-changelog/<base>-<next>.md. The report must be grounded in the real diff — added/modified/removed code, API/flag/dep deltas — not commit messages or the requirements docs (those describe the end state and the whole feature history, so they routinely credit the range with work that predates it, or describe posture that was already true). Every claim is a verified delta between the base tag and HEAD.

The two facts that make this skill necessary

1. HEAD is the next, unreleased version. package.json still holds the last released version, so the release number can't be read from the repo — you must ask the user what the next planned version is.
2. The base is always the most recent production release tag (e.g. v1.0.1), and the range is <base>..HEAD. Pre-release tags (-beta, -rc) are never the base.

Steps

1. Ask for the next release number first. Use AskUserQuestion (or ask in prose): "What's the next planned release version for this changelog?" Do not guess and do not read it from package.json (that's the previous release). Accept e.g. 1.2.0 / v1.2.0.

2. Run the analysis script — it does the deterministic git work:

   node scripts/changelog-analysis.mjs --next <version>
   

   It auto-detects the base as the newest production vX.Y.Z tag that is an ancestor of HEAD, buckets the line delta by area (product vs docs vs agent/skill scaffolding vs generated assets), gives a product-only total, lists added/removed files and candidate new subsystems, and extracts the API-export, CLI-flag, and dependency deltas. Override the base with --base <tag> only if the user asks (it warns if a newer production tag exists than the one it picked).

3. Read the real diffs — do not stop at the script. The script tells you where to look; the narrative comes from the actual changes. For each non-trivial area:

   git diff <base>..HEAD -- <path>          # what actually changed
   

   And verify every "new" claim against the base tree rather than trusting a commit subject:

   git cat-file -e <base>:<file>            # non-zero exit → file is genuinely new
   git show <base>:<file> | grep -c <sym>   # 0 → the symbol/behavior was added in range
   git ls-tree -r --name-only <base> -- src/   # what the tree looked like at the base
   

   Classic traps to check: a subsystem that looks new but existed at the base; a feature added and removed within the same range (nets to zero at HEAD — say so); posture like "no network" / "zero deps" that was already true at the base (baseline, not a change); a dependency bumped in two hops (report the full base→HEAD delta).

4. Write the report to docs/technical-changelog/<base>-<next>.md (the script prints the exact suggested path). Keep it to ~one page. It must contain, in this spirit:

   • Header: the range (<base>..HEAD), commit count, and a note that HEAD is untagged / the "next" number is a label. State it's derived from the diff, not commit prose.
   • Honest size: the area-by-area split from the script, and the product-only +/- total called out separately from the raw total (which is inflated by docs and .claude/.agents/.hotsheet scaffolding — never present the raw number as engineering effort).
   • Baseline note: one line on what already shipped at the base (so nothing pre-existing reads as new).
   • Per-change sections for the genuine deltas, each carrying its diff evidence (new files, the export/flag/dep delta, 0-hits → present for behavior). Order by significance (a net-new subsystem before a doc sync).
   • Mermaid diagrams as needed (not gratuitously): a component/flow diagram for a new subsystem, a sequence diagram for a new round-trip/interaction. Use <br/> for line breaks in node labels (not \n) and quote labels containing spaces/punctuation.

5. Validate + finish.

   • Sanity-check the mermaid blocks (balanced []/quotes; standard flowchart / sequenceDiagram syntax). If a renderer is available, render to confirm; otherwise a structural check is fine.
   • Re-read the draft against the script output and your git show <base>:… probes: is every claim a real delta? Cut or re-label anything that describes the baseline.
   • Committing is optional and follows the repo's git rules (commit when it's a clean unit; never git push without explicit permission).

Guardrails

• Diff over prose. If a claim isn't backed by a file/line change you actually read, don't make it. Commit subjects and docs/ are leads to verify, not sources to quote.
• Never inflate. Lead with product-only line counts; label docs and agent/skill scaffolding as non-engineering.
• Attribute to the range only. When unsure whether something is new, run the git cat-file -e <base>:<file> / git show <base>:<file> probe before writing it up.