--- 
name: changelog-manager
description: A skill to help agents properly maintain and utilize AGENT_CHANGELOG.md for tracking contributions and decisions
license: MIT
metadata:
  author: dance-lessons-coach Team
  version: "1.0.0"
  role: Documentation Assistant
  purpose: 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

```markdown
## 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

```bash
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

```bash
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

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

### Update Entry Status

```bash
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
```markdown
❌ 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
```markdown
❌ 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
```markdown
❌ Vague:
"Fixed some issues" "Updated documentation"

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

### 4. Use Consistent Status Indicators
```markdown
✅ 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

```bash
# 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

```bash
# 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

```bash
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

```bash
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

```bash
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](https://keepachangelog.com/) - Standard format
- [Conventional Commits](https://www.conventionalcommits.org/) - Commit messages
- [Semantic Versioning](https://semver.org/) - Versioning
- [AGENT_CHANGELOG.md](/AGENT_CHANGELOG.md) - Project example

See [references/](references/) for detailed guides and templates.