Maintaining Documentation After Code Changes

What this skill does

# Maintaining Documentation After Code Changes

## Overview

**Documentation drift is inevitable without systematic maintenance.** Code evolves rapidly while documentation becomes stale. This skill provides a two-phase workflow to keep project docs synchronized with code: analyze recent changes, then update and restructure documentation accordingly.

## When to Use

Use this skill when:
- Completing features or bugfixes (before marking work complete)
- Preparing to merge branches or create pull requests
- Git diff shows significant code changes
- Documentation feels stale, incomplete, or contradicts current code
- New functionality added without corresponding doc updates
- Onboarding reveals outdated or missing documentation
- API changes or new commands/tasks added
- Implementation challenges revealed better practices

**When NOT to use:**
- During active development (docs can lag slightly, update at checkpoints)
- For trivial changes (typo fixes, formatting)
- When no code has changed

## Critical Principle

**Maintaining existing documentation after code changes is NOT "proactively creating docs" - it's keeping current docs accurate.**

CLAUDE.md instructions about "don't proactively create documentation" apply to NEW documentation files for undocumented features. They do NOT apply to maintaining existing documentation after you change the code it documents.

**If you changed the code, you must update the corresponding documentation. No exceptions.**

## Common Rationalizations (And Why They're Wrong)

| Rationalization | Reality |
|----------------|---------|
| "I'll update docs in a follow-up PR" | Later rarely happens. Context is freshest now. Capture it. |
| "Commit messages are documentation enough" | Commit messages explain code changes, not user workflows. Both are needed. |
| "Code is self-documenting if well-written" | Code shows HOW. Docs explain WHY and usage patterns. Different purposes. |
| "Time pressure means ship now, document later" | Shipping undocumented changes creates support burden > time saved. |
| "Don't know if user wants docs updated" | If code changed, docs MUST update. Not optional. Ask about scope, not whether. |
| "Documentation is maintenance overhead" | Outdated docs are overhead. Current docs save time for everyone. |
| "Minimal accurate > comprehensive outdated" | False choice. This skill gives you accurate AND complete in 15-30 min. |
| "Different teams handle docs differently" | This skill IS the standard for this project. Follow it. |
| "Risk of making commit scope too large" | Documentation changes belong with code changes. Same PR = atomic change. |
| "Best practices docs only change for patterns" | If you discovered lessons during implementation, they belong in CLAUDE.md. |

**None of these are valid reasons to skip documentation maintenance.**

## Quick Reference

| Phase | Focus | Key Activities |
|-------|-------|----------------|
| **Analyze** | What changed? | git diff → review docs → identify gaps |
| **Update** | Sync docs | Update content → restructure → summarize changes |

## Implementation

### Phase 1: Analysis

**Goal:** Understand what changed and what documentation needs updating

1. **Review recent changes:**
   ```bash
   git diff [base-branch]...HEAD
   ```
   Examine the full diff to understand scope of changes

2. **Check existing documentation:**
   - README.md (main project docs)
   - CLAUDE.md (AI assistant guidance) - use `cipherpowers:maintaining-instruction-files` for size/quality
   - AGENTS.md (multi-agent instructions) - use `cipherpowers:maintaining-instruction-files` for size/quality
   - README_*.md (specialized documentation)
   - docs/ directory (practices, examples, plans)
   - Any project-specific doc locations

3. **Identify documentation gaps:**
   - New features without usage examples
   - Changed APIs without updated references
   - Implementation lessons not captured in CLAUDE.md
   - New best practices discovered during work
   - Implementation challenges and solutions
   - Known issues or limitations discovered
   - Commands/tasks that changed behavior

**Output of analysis phase:** List of specific documentation updates needed

### Phase 2: Update

**Goal:** Bring documentation into sync with current code

1. **Update content to reflect changes:**
   - Add new sections for new features
   - Update changed functionality (especially examples)
   - Document implementation details for complex components
   - Update usage examples with new functionality
   - Add troubleshooting tips from recent issues
   - Update best practices based on experience
   - Verify commands/tasks reflect current behavior

2. **Restructure for clarity:**
   - Remove outdated or redundant content
   - Group related topics together
   - Split large files if they've grown unwieldy
   - Fix broken cross-references
   - Ensure consistent formatting

3. **Document updates:**
   Provide summary of changes:
   - Files updated
   - Major documentation changes
   - New best practices added
   - Sections removed or restructured

## Documentation Standards

Follow project documentation standards defined in:
- ${CLAUDE_PLUGIN_ROOT}standards/documentation.md

**Key standards to verify:**
- Formatting and structure (headings, examples, status indicators)
- Content completeness (usage examples, troubleshooting)
- README organization (concise main file, README_*.md for specialized docs)

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Updating only README, missing other docs | Check CLAUDE.md, README_*.md, docs/ systematically |
| Not reviewing git diff | Always start with full diff to understand scope |
| Describing "what" without "why" | Explain rationale, not just functionality |
| Forgetting to update examples | Changed APIs must update all examples |
| Batch updating at project end | Update at natural checkpoints (feature complete, before merge) |
| Restructuring separately from updates | Restructure while updating to prevent redundant passes |
| Missing troubleshooting updates | Document edge cases and solutions discovered during work |

## What NOT to Skip

**These are consistently skipped under pressure. Check explicitly:**

**✅ MUST check every time:**
- [ ] git diff reviewed (full diff, not just summary)
- [ ] CLAUDE.md updated (best practices, lessons learned, implementation patterns)
- [ ] All README*.md files checked and updated
- [ ] Practices docs (principles/standards/workflows) updated if patterns changed
- [ ] docs/examples/ updated if usage changed
- [ ] Usage examples updated (not just prose)
- [ ] Troubleshooting section updated (if you debugged issues)
- [ ] Cross-references verified (links still work)

**Common blind spots:**
- CLAUDE.md (agents forget this captures lessons learned)
- Usage examples (agents update text but not code examples)
- Troubleshooting sections (agents assume commit messages are enough)
- Practices documentation (agents think only patterns change these)

## Red Flags - STOP and Review Docs

**Situations:**
- About to merge without checking documentation
- Examples still show old API or command syntax
- CLAUDE.md doesn't mention new patterns/practices discovered
- Onboarding someone would miss new functionality
- Can't remember what changed (didn't check git diff)
- Just finished debugging but no troubleshooting docs added

**Rationalizations (means you're about to skip docs):**
- "I'll update docs later"
- "Commit message is enough"
- "Code is self-documenting"
- "Time pressure"
- "User said ship it"
- "Not sure what user wants"
- "Different teams do it differently"
- "Don't want to overstep"

**All of these mean: Stop and run this workflow before proceeding.**

## Real-World Impact

**Without systematic maintenance:**
- Onboarding takes longer (outdated docs)
- Best practices lost (not captured in CLAUDE.md)
- Teammates confused by stale examples
- Support burden increases (troubleshooting not documented)
- Knowledge silos (changes not shared)

**Wit