changelog-updater

name	changelog-updater
description	Update CHANGELOG.md and TEST-CHANGELOG.md with new entries following Keep a Changelog format and token optimization principles. Use when adding changes to the changelog, documenting new features, fixes, or optimizations.

Changelog Updater

Updates CHANGELOG.md following the optimized format established in this project.

When to Use

• After completing features, fixes, or optimizations
• When user requests "update changelog" or "add to changelog"
• When documenting architectural changes or token optimizations

Format Requirements

File Structure

## [Unreleased]

### Added
**Feature Name** (YYYY-MM-DD)
- Bullet points describing what was added
- Impact metrics if applicable

### Changed
**Change Name** (YYYY-MM-DD)
- Bullet points describing what changed
- Before/after metrics when relevant

### Fixed
**Fix Name** (YYYY-MM-DD)
- Bullet points describing what was fixed
- Files modified and root cause when relevant

Token Optimization Principles

Apply these techniques when writing changelog entries:

Technique	Example	Benefit
Tables over prose	Use tables for comparisons/metrics	60-80% reduction
Pattern statements	"Philosophy: 'Don't echo back what caller knows'"	80% reduction
Consolidated redundancy	Combine similar entries into themed sections	50-70% reduction
One perfect example	Show one clear example instead of multiple	65-70% reduction
Eliminate teaching	State facts, don't explain basics	80% reduction

Entry Guidelines

Good entry structure:

**Feature Name - Key Metric** (2025-11-03)
- What was done (1-2 lines)
- Technical details if complex (2-3 lines max)
- Impact: tokens saved, performance gain, etc.
- Files modified: path/to/file.ext:lines

Avoid:

• Excessive technical detail (put in ai_docs/ instead)
• Redundant explanations
• Multiple paragraphs per bullet
• Teaching basic concepts

Instructions

Step 1: Read Current Changelog

# Read just the Unreleased section
grep -A 100 "## \[Unreleased\]" CHANGELOG.md | head -100

Step 2: Identify Correct Section

• Added: New features, capabilities, documentation, tools
• Changed: Modifications to existing functionality, optimizations, refactors
• Fixed: Bug fixes, error corrections, path updates

Step 3: Format Entry

Use this template:

**Title - Key Metric** (YYYY-MM-DD)
- Primary change description
- Technical implementation (if needed)
- Impact: quantifiable benefit
- Files: modified locations

For token optimizations, use table format:

**Optimization Suite - Total Savings** (YYYY-MM-DD)
| Component | Savings | Type | Impact |
|-----------|---------|------|--------|
| Item 1 | X tokens | Per session | Description |
| Item 2 | Y tokens | One-time | Description |
| **TOTAL** | **Z tokens** | **Per session** | **% of budget** |

Step 4: Add Entry

1. Find the correct section (### Added, ### Changed, or ### Fixed)
2. Add entry at the TOP of that section (after the header)
3. Maintain chronological order (newest first)
4. Ensure proper blank lines between entries

Step 5: Verify Format

Check:

• Date is today's date (YYYY-MM-DD)
• Entry is concise (<10 lines unless complex optimization)
• Metrics included when applicable
• No duplicate section headers
• Proper markdown formatting

Examples

Example 1: Feature Addition

### Added

**Agent Skills System** (2025-11-03)
- Created changelog-updater skill for consistent CHANGELOG.md updates
- Format: YAML frontmatter + markdown instructions + examples
- Features: Token optimization guidelines, format validation, Keep a Changelog compliance
- Location: .claude/skills/changelog-updater/SKILL.md

Example 2: Optimization

### Changed

**Agent Files Token Optimization - 55.7% Reduction** (2025-11-03)
- Rewrote all 31 `.claude/agents/*.md` files from verbose to minimal YAML
- Line reduction: 1,878 → 832 lines (1,046 removed, 55.7% savings)
- Architecture: Metadata only in files, full prompts loaded via MCP
- Impact: ~2,000-2,500 tokens saved per agent file load

Example 3: Bug Fix

### Fixed

**Claude Hooks Path References** (2025-11-03)
- Updated config_validator.py path construction (scripts/claude-hooks → .claude/hooks)
- Fixed _find_project_root() traversal logic for new structure
- Files: .claude/hooks/utils/config_validator.py:20,78-83
- Result: Hooks load correctly, file protection active, no startup errors

Example 4: Multi-Component Table

### Changed

**Token Optimization Suite - 21-28k Tokens Saved** (2025-11-03)
| Optimization | Savings | Type | Impact |
|--------------|---------|------|--------|
| MCP Tool Descriptions | 10,600 | Startup | 60-70% description reduction |
| Dead Code Prevention | 4,500-7,000 | Per session | Removed unused services |
| MinimalResponseSerializer | 6,000-8,000 | Per session | Eliminated echo responses |
| **TOTAL** | **21,720-26,580** | **Per session** | **10.9-13.3% of 200k budget** |

Best Practices

Be Concise

Good: "Optimized agent files: 1,878 → 832 lines (55.7% reduction)"

Too verbose: "We performed a comprehensive optimization of the agent file system by analyzing each of the 31 agent files and rewriting them to use a more concise format that reduced the total line count from 1,878 lines down to 832 lines which represents a 55.7% reduction in file size..."

Quantify Impact

Always include metrics when available:

• Token savings (per session, one-time, % of budget)
• Line reduction (before → after, % saved)
• Performance gains (time, memory, response size)
• File counts (files modified, lines changed)

Use Active Voice

Good: "Removed EnrichmentService (566 lines)"

Avoid: "EnrichmentService was removed (566 lines)"

Group Related Changes

If multiple related changes happened together, combine them:

Good (grouped):

**Hooks System Migration** (2025-11-03)
- Migrated from scripts/claude-hooks/ to .claude/hooks/
- Updated all path references in config_validator, pre_tool_use, test paths
- File system protection, documentation enforcement operational

Avoid (separate):

**Hooks Path Update** (2025-11-03)
- Migrated hooks to .claude/hooks/

**Config Validator Fix** (2025-11-03)
- Updated config_validator paths

**Test Paths Update** (2025-11-03)
- Fixed test path references

Validation Checklist

Before finalizing the changelog entry:

• Format: Follows Keep a Changelog structure
• Section: Entry in correct section (Added/Changed/Fixed)
• Date: Uses YYYY-MM-DD format
• Concise: Entry is scannable (<10 lines for most changes)
• Metrics: Includes quantifiable impact when available
• Files: References specific files/lines when relevant
• Token Optimized: Uses tables, patterns, consolidated format
• No Duplicates: Doesn't duplicate existing section headers
• Markdown: Proper formatting (**, -, backticks for code)

Supporting Files

For detailed guidance, see:

• EXAMPLES.md - Real-world examples from this project (189 lines, all patterns covered)
• TEMPLATES.md - Copy-paste templates for quick entry creation (267 lines, fill placeholders)
• VALIDATION.md - Validation commands, checklists, quality checks (212 lines, pre-commit verification)

Reference

• Keep a Changelog: https://keepachangelog.com/en/1.0.0/
• Semantic Versioning: https://semver.org/spec/v2.0.0.html
• Project token optimization principles: See CHANGELOG.md "Token Optimization Suite" section