dance-lessons-coach/.vibe/skills/changelog-manager/SKILL.md

name, description, license, metadata

name	description	license	metadata
changelog-manager	A skill to help agents properly maintain and utilize AGENT_CHANGELOG.md for tracking contributions and decisions	MIT	author version role purpose dance-lessons-coach Team 1.0.0 Documentation Assistant Maintain consistent, useful changelog entries

Changelog Manager Skill

A skill to help AI agents properly maintain and utilize AGENT_CHANGELOG.md for tracking contributions, decisions, and project direction. Ensures consistent format, relevant content, and iterative improvements.

🎯 Purpose

The changelog manager skill helps agents:

1. Understand when to update the changelog
2. Follow consistent format for entries
3. Include relevant information without bloat
4. Keep it iterative and focused
5. Reference past decisions effectively

📋 When to Update the Changelog

✅ Update After Each Session

• Completed significant work (feature, bugfix, refactor)
• Made important decisions (architecture, tooling, process)
• Changed project direction (priorities, focus areas)
• Resolved major issues (blockers, technical debt)

❌ Don't Update For

• Trivial changes (typo fixes, minor formatting)
• Routine maintenance (dependency updates, routine tests)
• Failed attempts (unless learning is valuable)
• Repetitive tasks (same task done multiple times)

📝 Entry Format Guide

Standard Entry Structure

## YYYY-MM-DD - [Brief Description]

**Status:** ✅/⏳/❌ [Completed/In Progress/Blocked]
**Commit:** `[hash]` (if applicable)

### What Was Done
- Concise bullet points of changes
- Focus on outcomes, not just actions
- Use active voice ("Implemented X", not "X was implemented")

### Why It Was Done
- Business rationale or problem solved
- Technical justification if relevant
- Link to issues/ADRs if applicable

### How It Was Done
- Key implementation details
- Tools/techniques used
- Challenges overcome

### Current Status
- ✅ Completed and validated
- ⏳ In progress - next steps listed
- ❌ Blocked - specify what's needed

### References
- Issue: #[number]
- ADR: [adr/XXXX](adr/XXXX.md)
- Commit: [hash](link)
- PR: #[number](link)

🚀 Commands

Add Changelog Entry

skill changelog-manager add-entry \
  --date "$(date +%Y-%m-%d)" \
  --description "Brief description of work" \
  --status "completed" \
  --what "- Implemented feature X\n- Fixed issue Y\n- Updated documentation Z" \
  --why "Solves problem A\nImproves metric B" \
  --how "Used tool C\nApplied pattern D" \
  --references "#42,adr/0001.md,commit abc123"

Arguments:

• --date: Entry date (default: today)
• --description: Brief summary (5-10 words)
• --status: completed, in_progress, or blocked
• --what: Bullet points of what was done
• --why: Rationale and business value
• --how: Implementation approach
• --references: Related issues, ADRs, commits

Validate Changelog Entry

skill changelog-manager validate-entry \
  --file AGENT_CHANGELOG.md \
  --checks "format,content,references"

Checks:

• format: Proper markdown structure
• content: Relevant information included
• references: Valid links to issues/ADRs
• compact: No unnecessary details

Find Related Entries

skill changelog-manager find-related \
  --file AGENT_CHANGELOG.md \
  --query "workflow optimization" \
  --output related-entries.md

Update Entry Status

skill changelog-manager update-status \
  --file AGENT_CHANGELOG.md \
  --date "2026-04-06" \
  --status "completed" \
  --note "Validated in production"

📚 Best Practices

1. Keep It Compact

❌ Too verbose:
"On April 6, 2026, I worked on implementing a new feature that involved creating several files, modifying configuration, and testing various scenarios. The process took several hours and required careful consideration of edge cases."

✅ Compact:
"Implemented feature X with edge case handling (3 files, 2 config changes)"

2. Focus on Outcomes

❌ Task-oriented:
"Created files A, B, C" "Modified config D" "Ran tests E, F, G"

✅ Outcome-oriented:
"Enabled feature X (3 new files, config update)" "Achieved 95% test coverage (7 new tests)"

3. Link to References

❌ Vague:
"Fixed some issues" "Updated documentation"

✅ Specific:
"Fixed #42 - CI workflow errors" "Updated adr/0001.md with lessons learned"

4. Use Consistent Status Indicators

✅ Completed and validated
⏳ In progress - next steps listed
❌ Blocked - specify what's needed
🎯 Planned - future work

5. Update Regularly

• After each significant session
• When status changes
• When new information is available
• At least weekly for active projects

📁 Workflow Integration

Typical Session Workflow

# 1. Start work session
vibe start --agent dancelessonscoachprogrammer

# 2. Do the work...
# ... implementation, testing, documentation ...

# 3. Update changelog
skill changelog-manager add-entry \
  --description "Implement workflow optimization" \
  --status "completed" \
  --what "- Combined 4 workflows into 1\n- Reduced CI time by 40%\n- Added artifact sharing" \
  --why "Faster builds, easier maintenance" \
  --how "Used job dependencies, conditional execution" \
  --references "#2,adr/0017.md,commit abc123"

# 4. Commit changes
git add . && git commit -m "✨ feat: optimize CI/CD workflow"
git push origin main

Example Workflow with Changelog

# Session: Implement feature X
vibe start --agent dancelessonscoachprogrammer

# ... work ...

# Update changelog
skill changelog-manager add-entry \
  --description "Add product owner agent" \
  --status "completed" \
  --what "- Created 4 supporting skills\n- Configured agent with 8 skills\n- Added interview templates" \
  --why "Automates 60% of PO workflow" \
  --how "Used skill-creator, TOML config" \
  --references "#42,adr/0008.md"

# Verify entry
skill changelog-manager validate-entry \
  --file AGENT_CHANGELOG.md \
  --checks "format,content,references"

# Commit
git add AGENT_CHANGELOG.md .vibe/skills/ && \
  git commit -m "✨ feat: add product owner agent system"

🔍 Validation Checks

Format Validation

skill changelog-manager validate-format \
  --file AGENT_CHANGELOG.md

Checks for:

• ✅ Proper markdown headers
• ✅ Consistent date format (YYYY-MM-DD)
• ✅ Bullet points for lists
• ✅ Code blocks for commands
• ✅ No excessive whitespace

Content Validation

skill changelog-manager validate-content \
  --file AGENT_CHANGELOG.md

Checks for:

• ✅ What/Why/How structure
• ✅ Status indicators
• ✅ References to issues/ADRs
• ✅ No implementation details
• ✅ Outcome focus

Reference Validation

skill changelog-manager validate-references \
  --file AGENT_CHANGELOG.md

Checks for:

• ✅ Issue #NNN exists
• ✅ ADR files exist
• ✅ Commit hashes are valid
• ✅ Links are functional

📚 References

• Keep a Changelog - Standard format
• Conventional Commits - Commit messages
• Semantic Versioning - Versioning
• AGENT_CHANGELOG.md - Project example

See references/ for detailed guides and templates.