V0.7.4/git keep a changelog

[gimlichael]

This pull request makes significant improvements to the git-keep-a-changelog skill to ensure concrete release changelogs always include the base commit, preventing accidental omission of foundational changes such as version bumps and release-prep updates. The documentation, evaluation criteria, and validation scripts are all updated to enforce and clarify this requirement, adding explicit instructions, checks, and examples for using <base>^..HEAD (with the caret) for concrete releases.

Changelog and Documentation Improvements:

• Updated README.md and skills/git-keep-a-changelog/SKILL.md to emphasize that for concrete releases, Step 4 must use <base>^..HEAD to include the base commit, with detailed explanations, examples, and explicit pre-Step 4 validation instructions. This ensures foundational changes are never omitted from the release changelog. [1] [2] [3] [4] [5]

Validation and Evaluation Enhancements:

• Added new assertions in scripts/validate-skill-templates.ps1 to check that the skill documentation and evaluation files require and describe the use of <base>^..HEAD for concrete releases, including explicit pre-Step 4 validation and reporting of the base commit. [1] [2]
• Extended skills/git-keep-a-changelog/evals/evals.json with a new evaluation scenario to verify that the workflow recognizes concrete releases, uses the correct commit range, and reports/analyzes the base commit before proceeding.

[greptile-apps]

Greptile Summary

This PR strengthens the git-keep-a-changelog skill by enforcing that concrete release changelogs always include the base commit via <base>^..HEAD, preventing silent omission of release-prep and version-bump changes. All four updated artifacts — SKILL.md, README.md, the validation script, and evals.json — are internally consistent and the previous duplicate "bad output" bullet has been cleanly resolved.

• SKILL.md: Adds a new ### Step 3b: Verify Your Approach section between Steps 3 and 4, expands Step 4a into a mandatory reporting gate, replaces the old brief "range extension" note with a CRITICAL block, and promotes the base-commit omission bullet to the top of "Bad Output Characteristics" while removing the older, weaker duplicate.
• validate-skill-templates.ps1: Adds five new Assert-Contains needles that exactly match the text introduced in SKILL.md and one needle for the new evals.json expectation string; all assertions verified against the diff.
• evals.json: Adds eval entry 14 with six targeted expectations covering step ordering, command syntax, and output reporting for the concrete-release base-commit scenario.

Confidence Score: 5/5

Safe to merge — all changes are documentation and test instructions with no executable logic paths affected.

The four changed files are skill instructions, a README, a validation script, and an eval fixture. Every new assertion needle was verified against the corresponding SKILL.md and evals.json text and matches exactly. The previous duplicate bad output bullet is cleanly removed. The only observation is a minor eval prompt design choice that does not affect correctness.

No files require special attention.

Important Files Changed

Filename	Overview
skills/git-keep-a-changelog/SKILL.md	Adds Step 3b for approach verification, expands Step 4a into a mandatory reporting gate, and promotes the base-commit omission bullet to CRITICAL — cleanly removes the old duplicate bullet.
scripts/validate-skill-templates.ps1	Five new Assert-Contains needles added for SKILL.md and one for evals.json; all needles verified as exact substrings of the corresponding added content.
skills/git-keep-a-changelog/evals/evals.json	New eval entry 14 covers concrete-release base-commit behaviour with six expectations; prompt explicitly hints at the expected outcome, which slightly reduces discriminating power between with-skill/without-skill runs.
README.md	Updates skill description and feature bullet to document the new concrete-release base coverage behaviour; changes are concise and accurate.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    S3["Step 3: Check pending worktree changes - Yes/No/Custom gate"] --> S3B["Step 3b: Verify Your Approach"]
    S3B --> Q{"Concrete release?"}
    Q -- Yes --> CARET["Use base^..HEAD - caret includes base commit"]
    Q -- No --> NOCARET["Use base..HEAD - no caret for Unreleased"]
    CARET --> S4A["Step 4a - MANDATORY GATE\nInspect base commit\ngit show + git diff stat"]
    NOCARET --> S4B
    S4A --> REPORT["Show full output\nIdentify manifests and release-prep files\nState files changed and manifests found"]
    REPORT --> CONFIRM["Step 4a Confirmation\nManifests touched? Y/N\nRelease-prep touched? Y/N"]
    CONFIRM --> S4B["Step 4b: Detect manifest changes across full range"]
    S4B --> S4C{"Any manifests changed?"}
    S4C -- Yes --> S4C_RUN["Step 4c: Diff manifests base to HEAD"]
    S4C -- No --> S4D["Step 4d: Read commit bodies"]
    S4C_RUN --> S4D
    S4D --> WRITE["Write CHANGELOG.md\nAdded / Changed / Fixed + compare-link footer"]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    S3["Step 3: Check pending worktree changes - Yes/No/Custom gate"] --> S3B["Step 3b: Verify Your Approach"]
    S3B --> Q{"Concrete release?"}
    Q -- Yes --> CARET["Use base^..HEAD - caret includes base commit"]
    Q -- No --> NOCARET["Use base..HEAD - no caret for Unreleased"]
    CARET --> S4A["Step 4a - MANDATORY GATE\nInspect base commit\ngit show + git diff stat"]
    NOCARET --> S4B
    S4A --> REPORT["Show full output\nIdentify manifests and release-prep files\nState files changed and manifests found"]
    REPORT --> CONFIRM["Step 4a Confirmation\nManifests touched? Y/N\nRelease-prep touched? Y/N"]
    CONFIRM --> S4B["Step 4b: Detect manifest changes across full range"]
    S4B --> S4C{"Any manifests changed?"}
    S4C -- Yes --> S4C_RUN["Step 4c: Diff manifests base to HEAD"]
    S4C -- No --> S4D["Step 4d: Read commit bodies"]
    S4C_RUN --> S4D
    S4D --> WRITE["Write CHANGELOG.md\nAdded / Changed / Fixed + compare-link footer"]

Loading

_{Reviews (2): Last reviewed commit: "♻️ restructure git-keep-a-changelog step..." | Re-trigger Greptile}