changelog-release-tracker

name	changelog-release-tracker
description	Generate or update the internal OpenWork release changelog tracker as plain markdown release sections. Triggers when user mentions: - "generate changelog markdown" - "track this release" - "add a changelog entry"

Purpose

Use this skill to add or update the OpenWork release tracker using release history from _repos/openwork.

The tracker is split into files named release-tracker-{YYYY-MM-DD}.md in _repos/openwork/changelog/, where the date is the first release date in that file; append to the latest file, or create a new one (dated today) when the latest file already has 25 entries.

Output Contract

• The output file must be plain markdown sections.
• Keep release sections sorted oldest to newest so new versions append at the end.
• If the tracker file already exists, preserve its formatting and append or edit ## <version> sections in place.
• Each subsection inside a release must start and use a #### heading.
• Use plain text under scalar subsections unless a subsection explicitly allows multiple markdown structures.
• Include a lines-of-code subsection and a release-importance subsection for every release.
• Include a Title subsection for every release.
• The Title must be concise, publish-ready, and reusable almost verbatim in the public changelog.
• The Title, One-line summary, and Main changes must complement each other instead of repeating the same wording at different lengths.
• Main changes may use the best-fit markdown structure described below instead of a fixed bullet count.

Inputs

• One or more release tags such as v0.11.101
• Optional output file path; default to the latest _repos/openwork/changelog/release-tracker-{YYYY-MM-DD}.md file (or a new one if it has 25 entries)

Steps

1. Work from a dedicated worktree and confirm the tracker file path.

2. In _repos/openwork, gather release metadata for each tag:

   gh release view <tag> --repo different-ai/openwork --json tagName,publishedAt,body
   git rev-list -n 1 <tag>
   git log --oneline --no-merges <previous-tag>..<tag>
   git diff --shortstat <previous-tag>..<tag>
   

3. Read nearby published entries in _repos/openwork/packages/docs/changelog.mdx before drafting language so the tracker entry matches the current public changelog voice.

4. Inspect any commit that looks user-facing before summarizing it:

   git show --stat --summary <sha>
   

5. Derive release values with these rules:

   • Commit: use the tag commit from git rev-list -n 1 <tag>, shortened to 8 characters.
   • Title: write one concise publish-ready line that states the release's core substance up front.
   • The Title should usually be 4-10 words, in sentence case, and focus on the most important user-facing or developer-facing outcome.
   • Lead the Title with the primary workflow, product surface, or capability that changed, not with a generic verb like Improves several areas.
   • The Title must be reusable almost verbatim as the release-level headline sentence in _repos/openwork/packages/docs/changelog.mdx, even though the public file does not have a separate Title field.
   • The Title should sound like a strong changelog headline: concrete, direct, and outcome-first.
   • Avoid version numbers, release-process wording, and filler such as This release, Shipped, Various, Several, or Miscellaneous.
   • Avoid internal-only implementation terms unless they are visible to users or directly relevant to developers, such as APIs, CLI flows, providers, MCP setup, or documented product surfaces.
   • Prefer visible nouns and surfaces such as workspace switching, session loading, Settings, Cloud sign-in, skill editing, , or over repo mechanics or internal package names.

Common Gotchas

• The final file is markdown text, not a markdown table embedded inside a markdown file.
• Subsection headings are required so entries are easier to target programmatically.
• Do not treat the release bump commit as a feature by itself.
• Use the release body to anchor the summary, but use commit inspection to verify the real user-facing changes.
• Keep Main changes user-facing or developer-facing in a visible way; avoid internal implementation details unless they matter to the actual workflow.
• Do not write a vague Title like Improves reliability and fixes bugs; the title should identify the actual workflow or surface that changed.
• Do not make the Title, One-line summary, and opening Main changes content say the same thing three times with minor wording changes.
• When a release has little visible product impact, say that plainly instead of inflating the language.
• Do not force Main changes into 3 bullets when a short paragraph or lead-plus-list structure is clearer.
• Do not use an indented code snippet unless the code itself is part of the user-facing or developer-facing story.
• Do not let Main changes exceed 80 words just because the release was large; choose a tighter structure or move detail to another field.