docs-maintenance

# Documentation Maintenance Skill

Comprehensive methodology for keeping project documentation current, consistent, and optimized for AI coding agents.

## When to Use

- Synchronizing documentation with recent code changes
- Optimizing CLAUDE.md for AI agent effectiveness
- Updating README to reflect current project state
- Adding CHANGELOG entries for undocumented changes
- Auditing documentation freshness and accuracy
- Ensuring cross-document consistency

## Documentation Update Phases

### Phase 1: Documentation Inventory

1. Find all documentation files in the project:
   - `CLAUDE.md` - AI agent instructions
   - `README.md` - Project overview
   - `CHANGELOG.md` - Version history
   - `/docs/` directory - Extended documentation
   - Inline documentation (JSDoc, docstrings, comments)
2. Record last modified dates for each doc
3. Identify documentation types and their purposes
4. Note any missing essential documentation

### Phase 2: Git History Analysis

1. Get commits since last documentation update:
   ```bash
   git log --oneline --since="$(git log -1 --format=%ci -- CLAUDE.md)"
   ```
2. Identify changes that need documentation:
   - New files or directories added
   - Configuration changes (package.json, tsconfig.json, etc.)
   - New commands, scripts, or entry points
   - API changes (new endpoints, modified signatures)
   - Dependency updates
   - Removed or deprecated features
3. Flag commits with keywords: "add", "remove", "breaking", "fix", "feat"
4. Check for removed features still documented

### Phase 3: CLAUDE.md Optimization

Verify CLAUDE.md includes essential sections:

**Required Sections:**
- [ ] Project Overview - What the project does
- [ ] Build/Test Commands - Exact commands to run
- [ ] Key File Locations - Important directories and files
- [ ] Architecture Overview - How components connect
- [ ] Coding Conventions - Naming patterns, style preferences
- [ ] Common Pitfalls - Things AI agents often get wrong
- [ ] Tool/Dependency Notes