[changelog] Refine changelog entries and skill guidance

Author: coisa

.agents/skills/changelog-generator/SKILL.md

@@ -1,153 +1,102 @@
 ---
 name: changelog-generator
-description: Generate and maintain CHANGELOG.md following Keep a Changelog format with human-readable descriptions. Use when: (1) Creating initial changelog from git tags, (2) Updating changelog for new releases, (3) Generating unreleased section for pull requests. Rule: NEVER use commit messages as source of truth - analyze code diffs instead.
+description: Generate or refresh human-readable CHANGELOG.md files that follow Keep a Changelog by comparing git tags and code diffs instead of commit messages. Use when Codex needs to bootstrap a changelog for a repository, backfill undocumented tagged releases, update release entries, or rewrite the Unreleased section for current branch work using the phly/keep-a-changelog commands available in the project.
 ---
 
 # Changelog Generator
 
-Generates and maintains CHANGELOG.md following the Keep a Changelog format with clear, specific, and self-sufficient descriptions.
+Generate changelog entries that a reader can understand without opening the code.
 
-## Dependencies
+## Deterministic Helpers
 
-- `phly/keep-a-changelog` - Installed in project
-- Git - For analyzing code changes
-- GitHub CLI (`gh`) - For reading PR context
-- Filesystem - For reading/writing CHANGELOG.md
+Use the bundled PHP scripts before manual analysis:
 
-## PR Context Integration
-
-When generating changelog for changes that belong to a PR:
-
-1. Detect PR reference: Check git branch name or recent PR comments
-2. Fetch PR description: Use `gh pr view <pr-number> --json body`
-3. Extract context: Read the PR Summary and Changes sections
-4. Enhance descriptions: Use PR context to write more accurate changelog entries
-
-Example workflow:
 ```bash
-# Detect current PR
-BRANCH=$(git branch --show-current)
-PR_NUM=$(echo "$BRANCH" | grep -oE '[0-9]+' | head -1)
-
-# Fetch PR context if exists
-if [ -n "$PR_NUM" ]; then
-  PR_BODY=$(gh pr view "$PR_NUM" --json body --jq '.body')
-  # Use PR body as an extra context to define the changelog descriptions
-fi
+php .agents/skills/changelog-generator/scripts/changelog-state.php
+php .agents/skills/changelog-generator/scripts/diff-inventory.php <from-ref> <to-ref>
 ```
 
-This ensures changelog descriptions align with the PR intent and provide better context.
-
-## Key Commands
+- `changelog-state.php` reports changelog presence, documented versions, discovered tags, undocumented tags, and suggested release ranges as JSON.
+- `diff-inventory.php` reports changed files, line counts, and likely user-visible paths for a specific diff range as JSON.
+- Both scripts auto-discover the repository root and opportunistically load `vendor/autoload.php` when it exists.
+
+## Workflow
+
+1. Establish current state.
+- Read `CHANGELOG.md` if it exists.
+- Prefer `changelog-state.php` to gather versions and ranges before inspecting files manually.
+- Record documented versions and whether `## Unreleased - TBD` already exists.
+- List tags in ascending semantic order with `git tag --sort=version:refname`, and capture their commit dates when the repository may have retroactive or out-of-sequence tags.
+- Treat commit messages as navigation hints only; never derive final changelog text from them.
+
+2. Choose diff ranges.
+- If `CHANGELOG.md` is missing or empty, analyze each tag range from the first tagged version onward.
+- If `CHANGELOG.md` already documents releases, start at the first tag after the last documented version.
+- When tag publication order differs from semantic order, prefer the actual tag chronology for release ordering and use diffs that follow that real release sequence.
+- Build `Unreleased` from the diff between the latest documented release or tag and `HEAD`.
+
+3. Analyze changes from diffs.
+- Prefer `diff-inventory.php <from> <to>` first so you can focus on the files most likely to affect user-visible behavior.
+- Start with `git diff --name-status <from> <to>` and `git diff --stat <from> <to>`.
+- Open targeted `git diff --unified=0 <from> <to> -- <path>` views for files that define public behavior, commands, config, schemas, workflows, or exposed APIs.
+- Classify entries by observed impact:
+  - `Added`: new files, APIs, commands, options, configuration, workflows, or user-visible capabilities
+  - `Changed`: modified behavior, signature or default changes, renamed flows, or compatibility-preserving refactors with visible impact
+  - `Fixed`: bug fixes, validation corrections, edge-case handling, or broken workflows
+  - `Removed`: deleted APIs, commands, config, or capabilities
+  - `Deprecated`: explicit deprecation notices or migration paths
+  - `Security`: hardening or vulnerability fixes
+- Skip pure churn that a reader would not care about unless it changes behavior or release expectations.
+- Deduplicate multiple file changes that describe the same user-visible outcome.
+
+4. Write human-readable entries.
+- Write one line per change.
+- Prefer the functional effect over implementation detail.
+- Mention the concrete command, class, option, workflow, or API when that improves comprehension.
+- When a matching PR exists, append it to the line in the format `(#123)` after the diff already supports the entry.
+- Avoid vague phrases such as `misc improvements`, `refactorings`, or `code cleanup`.
+
+5. Apply changes with project tooling.
+- Prefer the local wrappers when available:
 
 ```bash
-vendor/bin/changelog             # Main CLI
-vendor/bin/changelog add:entry   # Add entry to version
-vendor/bin/changelog release    # Create release
+composer dev-tools changelog:init
+composer dev-tools changelog:check
 ```
 
-## Execution Pipeline (Deterministic)
-
-### Stage 1: Initial State
-
-1. Check if CHANGELOG.md exists and has content:
-   ```bash
-   ls -la CHANGELOG.md 2>/dev/null || echo "NO_FILE"
-   ```
-
-### Stage 2: Version Discovery
-
-1. List all tags sorted semantically:
-   ```bash
-   git tag --sort=-version:refname
-   ```
-
-2. Identify:
-   - Last documented version in CHANGELOG
-   - Tags not yet documented
-
-### Stage 3: Historical Content Generation
-
-**Case A: No CHANGELOG or Empty**
-
-For each tag (ascending order):
-1. Calculate diff between current tag and previous tag (or first commit for initial version)
-2. Analyze code diff to infer changes (NOT commit messages)
-3. Group changes by type (Added, Changed, Fixed, Removed, Deprecated, Security)
-4. Insert version section
-
-**B: Existing CHANGELOG**
-
-1. Identify last documented version
-2. For each subsequent tag:
-   - Generate diff between versions
-   - Insert new section in changelog
-
-### Stage 4: Unreleased Section
-
-1. Calculate diff between last documented tag and HEAD
-2. Generate [Unreleased] section with current changes
-
-## Change Classification (Inferred from Diff)
-
-Analyze actual code changes, NOT commit messages:
-
-| Pattern | Category |
-|---------|----------|
-| New files, new classes, new methods | Added |
-| Behavior changes, refactors, signature changes | Changed |
-| Bug fixes, validation fixes | Fixed |
-| Deleted classes, removed methods | Removed |
-| @deprecated markers | Deprecated |
-| Security patches | Security |
-
-## Quality Rules
-
-- **SHORT**: One line per change
-- **SPECIFIC**: Include class/method names
-- **SELF-SUFFICIENT**: Understand without reading code
-- **FUNCTIONAL**: Describe impact, not implementation
-- **PR-AWARE**: Use PR description to enhance accuracy when available
-
-Good: "Added `Bootstrapper::bootstrap()` to create CHANGELOG.md when missing"
-Bad: "Add bootstrap command"
-
-## PR Context Usage
-
-When a PR number is available:
-
-1. Read PR description for implementation intent
-2. Extract key capabilities mentioned in Summary
-3. Use specific feature names from the PR to write accurate descriptions
-4. Reference PR in changelog: "Added changelog automation (#40)"
-
-## Integration with keep-a-changelog
-
-Use CLI commands when possible:
+- Use the official CLI for entries and releases:
 
 ```bash
-# Add unreleased entry
-vendor/bin/changelog add:entry --unreleased --type=added "Description"
+vendor/bin/keep-a-changelog entry:added "..."
+vendor/bin/keep-a-changelog entry:changed "..."
+vendor/bin/keep-a-changelog entry:fixed "..."
+vendor/bin/keep-a-changelog unreleased:create --no-interaction
+vendor/bin/keep-a-changelog unreleased:promote 1.2.0 --date=2026-04-12 --no-interaction
+vendor/bin/keep-a-changelog version:show 1.2.0
+vendor/bin/keep-a-changelog version:release 1.2.0 --provider-token=...
+```
 
-# Add release entry
-vendor/bin/changelog add:entry 1.0.0 --type=added "Description"
+- For large historical backfills, direct markdown editing is acceptable for the first draft. After that, use the CLI to keep `Unreleased` and future entries consistent.
 
-# Create release
-vendor/bin/changelog release 1.0.0 --date="2026-04-11"
-```
+6. Verify the result.
+- Keep `Unreleased` first and released versions in reverse chronological order.
+- Keep section order as `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`.
+- Do not duplicate the same change across sections or versions.
+- Ensure every documented version maps to a real tag or intentional unreleased state.
+- Run local helpers such as `composer dev-tools changelog:check` when the project provides them.
+
+## PR Context
 
-Edit CHANGELOG.md directly if CLI insufficient.
+Use PR descriptions, issue text, or release notes only to refine wording after diff analysis confirms the change. Good uses:
 
-## Verification
+- naming a feature exactly as presented to users
+- adding a stable reference like `(#123)`
+- understanding why a visible change matters when the diff alone is ambiguous
 
-Valid changelog MUST have:
-- All sections: Added, Changed, Deprecated, Removed, Fixed, Security
-- No "Nothing." placeholders (unless truly empty)
-- Reverse chronological order (newest first)
-- [Unreleased] at top when applicable
+Do not use PR text to invent entries that are not supported by the code diff.
 
 ## Reference Files
 
-- [references/keep-a-changelog-format.md](references/keep-a-changelog-format.md) - Format spec
-- [references/change-categories.md](references/change-categories.md) - Classification guide
-- [references/description-patterns.md](references/description-patterns.md) - Human-readable patterns
+- Read [references/keep-a-changelog-format.md](references/keep-a-changelog-format.md) for heading format, section order, and CLI mapping.
+- Read [references/change-categories.md](references/change-categories.md) when the diff spans multiple change types.
+- Read [references/description-patterns.md](references/description-patterns.md) when the first draft still sounds too internal or vague.

.agents/skills/changelog-generator/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Fast Forward Changelog Generator"
-  short_description: "Generate and maintain Keep a Changelog entries"
-  default_prompt: "Use $changelog-generator to create CHANGELOG.md from git tags"
+  short_description: "Generate changelog entries from Git diffs"
+  default_prompt: "Use $changelog-generator to generate or refresh CHANGELOG.md from git tags, code diffs, and current unreleased work."

.agents/skills/changelog-generator/references/change-categories.md

@@ -12,6 +12,8 @@ Infer category from code patterns, NOT from commit messages.
 - New configuration options
 - New CLI commands
 - New public APIs
+- New workflows or automation files
+- New user-visible documentation pages that introduce a capability
 
 **Examples:**
 - `+class Bootstrapper` → "Added `Bootstrapper` class for changelog bootstrapping"
@@ -25,6 +27,7 @@ Infer category from code patterns, NOT from commit messages.
 - Changed default values
 - Behavior modifications
 - Refactors that affect the public API
+- Workflow or release process changes that alter contributor expectations
 
 **Examples:**
 - `function foo($bar)` → `function foo($bar, $baz = null)` → "Changed `foo()` to accept optional `$baz` parameter"
@@ -37,6 +40,7 @@ Infer category from code patterns, NOT from commit messages.
 - Validation improvements
 - Edge case handling
 - Error handling corrections
+- Broken automation or CI repairs
 
 **Examples:**
 - Empty input validation, null checks → "Fixed handling of null input in `parse()`"
@@ -48,6 +52,7 @@ Infer category from code patterns, NOT from commit messages.
 - Deleted classes
 - Deleted methods
 - Deleted configuration options
+- Removed commands or workflows
 
 **Examples:**
 - `-class LegacyParser` → "Removed deprecated `LegacyParser` class"
@@ -58,6 +63,7 @@ Infer category from code patterns, NOT from commit messages.
 **Patterns:**
 - @deprecated annotations
 - Deprecation notices in code
+- Migration warnings that keep the old surface available for now
 
 **Examples:**
 - `@deprecated` → "Deprecated `LegacyParser`, use `MarkdownParser` instead"
@@ -68,7 +74,24 @@ Infer category from code patterns, NOT from commit messages.
 - Security patches
 - Vulnerability fixes
 - Input sanitization
+- Permission hardening or secret-handling fixes
 
 **Examples:**
 - XSS fixes → "Fixed XSS vulnerability in user input"
-- CSRF protection → "Added CSRF protection to form handling"
+- CSRF protection → "Added CSRF protection to form handling"
+
+## Tie-breakers
+
+When a change could fit multiple categories, prefer the most specific outcome:
+
+1. `Security` over every other category
+2. `Removed` when the old surface is actually gone
+3. `Deprecated` when the old surface still exists but has a migration path
+4. `Fixed` for bug repairs, even if files or methods were added to implement the fix
+5. `Added` for genuinely new capability
+6. `Changed` as the fallback for user-visible behavior shifts
+
+## Skip or compress
+
+- Skip purely internal renames, file moves, or test-only churn unless they change behavior or contributor workflow.
+- Compress multiple file edits into one entry when they describe the same visible outcome.

.agents/skills/changelog-generator/references/description-patterns.md

@@ -4,14 +4,12 @@
 
 Rule: Describe the IMPACT, not the IMPLEMENTATION.
 
-## Quality Criteria
+## Checklist
 
-| Criterion | Good | Bad |
-|-----------|------|-----|
-| Specific | "Added `ChangelogCheckCommand` to verifies that the changelog contains pending unreleased notes." | "Added new feature" |
-| Short | One line | Paragraph |
-| Self-sufficient | "Creates CHANGELOG.md with all current version released" | "Bootstrap support" |
-| Actionable | "Added `--filter` option on TestsCommand to be able to filter test pattern classes" | "Improved CLI" |
+- Keep each entry to one line.
+- Name the surface that changed: class, command, option, workflow, API, or config.
+- Describe the user-visible effect first.
+- Avoid implementation verbs such as `extract`, `rename`, `refactor`, or `reorganize` unless the refactor itself changes behavior.
 
 ## Transformation Examples
 
@@ -22,7 +20,7 @@ Bad: "feat: add bootstrap"
 Good: "Added `Bootstrapper` class to create CHANGELOG.md when missing"
 
 Bad: "refactor: extract to new class"
-Good: "Extracted `CommitClassifier` for improved separation of concerns"
+Good: "Changed changelog generation to classify release entries by observed diff impact"
 
 Bad: "fix: validate unreleased notes"
 Good: "Fixed validation of unreleased changelog entries"
@@ -31,34 +29,38 @@ Bad: "chore: update dependencies"
 Good: N/A - Skip infrastructure-only changes
 ```
 
-## Class Names Pattern
+## Description templates
 
-Always include class/method names:
+Use these patterns when they fit the diff:
 
 ```markdown
-- Added `Bootstrapper` to bootstrap changelog assets
-- Added `MarkdownRenderer::render()` for generating output
-- Changed `Config::load()` to accept optional path parameter
-- Fixed `Parser::parse()` handling of empty input
+- Added `<surface>` to `<do what>` for `<benefit>`
+- Changed `<surface>` to `<new behavior>`
+- Fixed `<failure mode>` in `<surface>`
+- Removed deprecated `<surface>`
+- Deprecated `<surface>`; use `<replacement>`
 ```
 
-## API Changes Pattern
+## Concrete examples
 
 ```markdown
-- Added `CommandInterface::execute()` method
-- Changed `Parser::parse($input)` to accept optional `$options` array
+- Added `changelog:init` to bootstrap `.keep-a-changelog.ini` and `CHANGELOG.md`
+- Changed changelog sync to install reusable release-note workflows
+- Fixed bootstrap of the `Unreleased` section for existing changelog files
 - Removed deprecated `LegacyCommand`
-- Deprecated `Parser::process()`, use `Renderer::render()` instead
+- Deprecated `Parser::process()`; use `Renderer::render()` instead
 ```
 
-## Reference Patterns (PR)
+## Optional references
 
-When changes came from a PR:
+Append issue or PR references only when they add useful context and the diff already supports the entry:
 
 ```markdown
-- Added changelog automation (#28)
+- Added changelog automation (#40)
 - Changed workflow to use PHP 8.3 (#31)
 - Fixed validation bug (#42)
 ```
 
-This helps users find more context in PR history.
+When a matching pull request exists, prefer appending the PR reference in the format `(#123)` at the end of the line.
+
+Do not rely on the PR text as the source of truth.