gh-bradleyboehmke-brads-marketplace-document-generator/commands/validate-changelog.md

description

description
Validate existing CHANGELOG.md against standards

Validate Changelog

Objective

Validate existing CHANGELOG.md against standards (Keep a Changelog format) and report compliance issues with severity levels.

Activated Skills

1. changelog-standards (document-generator) - changelog format and structure
2. version-validation (document-generator) - Versioning rules and validation

Parameters

• --path (optional): Changelog location (auto-detects if not specified)
• --fix (optional): Automatically fix common formatting issues
• --output (optional): console (default) or markdown (generate validation report)

Process

1. Locate Changelog

Locate changelog file:

• If --path specified: Use that location
• Otherwise auto-detect from standard locations:
  • CHANGELOG.md (root)
  • docs/CHANGELOG.md
  • docs/changelog/*.md (yearly format)
  • Search for **/CHANGELOG.md or **/changelog/*.md

If not found:

❌ CHANGELOG.md not found

No changelog file detected in standard locations.

Run /document-generator:generate-changelog to create one.

2. Parse Changelog Structure

Read and extract:

• File header (title, preamble)
• [Unreleased] section
• Version entries with dates and tiers
• Changelog sections (Added, Changed, Fixed, etc.)
• Version comparison links

3. Validate Format

Apply changelog-standards skill to check:

Header Validation

• ✓ Has "# Changelog" or "# Change Log" title
• ✓ References Keep a Changelog format
• ⚠️ Missing header is a warning (not error)

Version Heading Validation

• ✓ Format: ## [VERSION] - YYYY-MM-DD or ## [VERSION] - YYYY-MM-DD [TIER]
• ❌ Missing brackets around version
• ❌ Incorrect date format (not YYYY-MM-DD)
• ⚠️ Invalid tier annotation

Examples:

## [2.1.0] - 2025-11-01 [MVP]     ✓ Valid
## [2025.1] - 2025-01-15          ✓ Valid
## v2.1.0 - 2025-11-01             ❌ No brackets
## [2.1.0] - 11/01/2025            ❌ Wrong date format
## [2.1.0] - 2025-11-01 [Alpha]   ⚠️ Invalid tier (use Prototype)

Section Validation

• ✓ Uses standard sections (Added, Changed, Deprecated, Removed, Fixed, Security)
• ⚠️ Non-standard sections (Features, Bugs, etc.)
• ✓ Sections in correct order
• ⚠️ Empty sections (should remove or populate)

Link Validation

• ✓ Version comparison links at bottom
• ✓ Links follow format: [VERSION]: URL
• ⚠️ Missing links for versions
• ❌ Broken link format

4. Validate Versions

Apply version-validation skill to check:

Version Format

• ✓ Matches SemVer pattern (X.Y.Z)
• ✓ Matches CalVer pattern (YYYY.N or YYYY.MM.N)
• ❌ Invalid version format
• ⚠️ Mixed version types (both SemVer and CalVer)

Version Ordering

• ✓ Versions in reverse chronological order (newest first)
• ❌ Out-of-order versions
• ⚠️ Skipped versions (1.0.0 → 1.2.0, missing 1.1.0)

Version Increments

• ✓ Proper SemVer increments
• ✓ Proper CalVer increments
• ❌ Invalid increment (e.g., 2.1.5 → 2.3.0, skipped 2.2.x)

Date Validation

• ✓ Valid ISO dates (YYYY-MM-DD)
• ❌ Invalid date format
• ❌ Invalid date (e.g., Feb 30)
• ⚠️ Dates not in chronological order
• ⚠️ Future dates (minor warning)

5. Generate Validation Report

Categorize issues by severity:

Errors (❌) - Must fix:

• Invalid version format
• Invalid date format
• Out-of-order versions
• Broken heading structure

Warnings (⚠️) - Should fix:

• Missing tier annotations
• Skipped versions
• Non-standard sections
• Missing version links
• Empty sections

Info (ℹ️) - Nice to have:

• Missing header preamble
• Future dates
• Inconsistent formatting

Output format (console):

Validating CHANGELOG.md...

❌ Errors (3)
  Line 15: Invalid version format "v2.1.0" (should be "[2.1.0]")
  Line 23: Invalid date format "11/01/2025" (should be "YYYY-MM-DD")
  Line 30: Versions out of order ([1.5.0] before [2.0.0])

⚠️  Warnings (2)
  Line 42: Skipped version 1.1.0 (jumped from 1.0.0 to 1.2.0)
  Line 67: Non-standard section "Bugs" (use "Fixed")

ℹ️  Info (1)
  Missing version comparison links at bottom of file

Overall: Failed (3 errors, 2 warnings)

6. Auto-fix (if --fix enabled)

Automatically correct common issues:

Fixable issues:

• Add brackets around versions: v2.1.0 → [2.1.0]
• Standardize date format: 11/01/2025 → 2025-11-01
• Rename sections: Bugs → Fixed, Features → Added
• Add missing header preamble
• Generate version comparison links

Not auto-fixable (manual intervention required):

• Out-of-order versions (need reordering)
• Invalid dates (need manual correction)
• Skipped versions (intentional or error?)

If --fix enabled:

Fixing common issues...

✓ Fixed 5 issues automatically
  - Standardized 2 version formats
  - Corrected 2 date formats
  - Renamed 1 section

⚠️  2 issues require manual fix
  - Line 30: Reorder versions manually
  - Line 42: Confirm if version 1.1.0 was intentionally skipped

Updated CHANGELOG.md saved.

7. Output Results

Console output (default):

• Display validation summary
• List all errors and warnings with line numbers
• Provide fix suggestions
• Show overall pass/fail status

Markdown report (if --output=markdown):

• Save to ./reports/changelog-validation-report.md
• Include all issues with context
• Link to changelog file
• Provide remediation steps

Output Format

Console (Default)

Validating CHANGELOG.md...

✓ Header present
✓ Keep a Changelog format referenced
✓ [Unreleased] section present
✓ 5 versions found

Checking versions...
  [2.1.0] ✓
  [2.0.0] ✓
  [1.5.0] ⚠️  Missing tier annotation
  [1.0.0] ✓

Checking format...
  ✓ All sections use standard names
  ✓ Versions in correct order
  ⚠️  2 versions missing comparison links

Summary:
- Errors: 0
- Warnings: 3
- Overall: Pass with warnings

Next steps:
1. Add tier annotations to versions
2. Generate comparison links at bottom

Markdown Report (--output=markdown)

Same structure as console output above, saved to ./reports/changelog-validation-report.md with:

• Full issue details with line numbers and context
• Fix recommendations for each issue
• Links to changelog file
• Remediation steps by priority

Examples

Basic validation:

/document-generator:validate-changelog
→ Validates CHANGELOG.md and displays results in console

Auto-fix issues:

/document-generator:validate-changelog --fix
→ Validates and automatically fixes common formatting issues

Generate report:

/document-generator:validate-changelog --output=markdown
→ Saves validation report to ./reports/changelog-validation-report.md

Combined:

/document-generator:validate-changelog --fix --output=markdown
→ Fixes issues and generates report

Custom location:

/document-generator:validate-changelog --path=docs/CHANGELOG.md
→ Validates changelog at docs/CHANGELOG.md

Constraints

• Token budget: Keep concise, delegate validation logic to skills
• Non-destructive by default (use --fix to modify)
• Preserve user content, only fix format
• Clear severity distinctions (error vs warning vs info)