Documentation Auto-Update Skill

Intelligent documentation maintenance based on git changes with cross-reference validation, staleness reporting, and multi-model consensus for critical updates.

Quick Start

# Update README based on current branch changes
/sc:readme

# Multi-document review and update (all project docs)
/sc:readme --scope all

# Target specific documentation
/sc:readme --scope api-docs

# Preview changes without writing
/sc:readme --preview

# Analyze N recent commits instead of branch diff
/sc:readme --commits 20

# Force PAL consensus for all updates
/sc:readme --consensus

# Compare against different base branch
/sc:readme --base develop

# Staleness report only (no changes)
/sc:readme --report-only

Behavioral Flow

1. DISCOVER - Run git diff or git log to find changed files
2. ANALYZE - Read changed files, categorize by type (API, config, deps, features)
3. MAP - Match changed files to affected documentation using source-of-truth mapping
4. VALIDATE - Cross-reference consistency checks across all docs
5. PLAN - Identify sections needing updates, generate staleness report
6. GENERATE - Update documentation sections via Edit tool
7. VERIFY - Review final docs with PAL codereview

Flags

Git Commands Used

# Branch diff mode (default)
git diff main...HEAD --name-status
git diff main...HEAD
git log main...HEAD --oneline

# Commit mode (--commits N)
git log --oneline -N --name-only --pretty=format: | sort -u | grep -v '^$'
git log --oneline -N

Change Categories

Multi-Document Mode (--scope all)

When --scope all is used, discover and validate all documentation files in the project.

Document Discovery

Auto-detect documentation files:

# Find all markdown docs (excluding node_modules, .venv, etc.)
find . -name "*.md" -not -path "*/node_modules/*" -not -path "*/.venv/*" -not -path "*/dist/*"

Common documentation patterns:

Source-of-Truth Mapping

Map code changes to affected documentation:

Cross-Reference Validation

When --cross-ref is enabled (default), verify consistency across docs:

• API routes mentioned in README match actual route handlers
• Environment variables match across all docs and .env.example
• File paths referenced in docs actually exist (via Glob)
• Component names are consistent across all documentation
• Documented commands are syntactically valid

Staleness Report

## Documentation Staleness Report

**Commits Analyzed**: 20 | **Docs Scanned**: 6 | **Issues Found**: 3

### README.md
**Status**: STALE
**Affected by**: src/api/users.py, src/models/user.py

- [ ] API Routes table missing new `/users/bulk` endpoint
- [ ] Environment variables section missing `BULK_IMPORT_LIMIT`

### docs/DATABASE.md
**Status**: UP-TO-DATE
No changes needed.

### frontend/README.md
**Status**: STALE
**Affected by**: src/components/UserProfile.tsx

- [ ] Component list missing UserProfile

Update Order

Process documents in dependency order:

1. README.md first (primary reference)
2. CLAUDE.md second (must stay consistent with README)
3. Other docs after (reference README as source of truth)

MCP Integration

PAL MCP

# Consensus for API/breaking changes
mcp__pal__consensus(
    models=[{"model": "gpt-5.2", "stance": "for"}, {"model": "gemini-3-pro", "stance": "against"}],
    step="Evaluate: Does this documentation update accurately reflect the code changes?",
    relevant_files=["/README.md", "/src/changed_file.py"]
)

# Review final documentation
mcp__pal__codereview(
    review_type="quick",
    step="Review documentation accuracy and cross-reference consistency",
    relevant_files=["/README.md", "/docs/API.md"]
)

Tool Coordination

• Bash - Git commands (git diff, git log)
• Read - Documentation files, changed source files
• Edit - Update documentation sections in-place
• Glob - File path validation, doc discovery
• Grep - Cross-reference checks, pattern validation

Examples

Single README Update

/sc:readme
# 1. git diff main...HEAD --name-status
# 2. Read README.md + changed files
# 3. Identify sections needing updates
# 4. PAL consensus if API changes detected
# 5. Update README.md

Multi-Document Review

/sc:readme --scope all --commits 20
# 1. git log --oneline -20 for change context
# 2. Discover all .md documentation files
# 3. Map changes to affected docs
# 4. Cross-reference validation
# 5. Generate staleness report
# 6. Update all affected docs

Staleness Report Only

/sc:readme --report-only --scope all
# Generates report without making changes

Preview Mode

/sc:readme --preview
# Same analysis, but output proposed changes instead of writing

Guardrails

1. Back up docs before modifications
2. Never remove sections without user confirmation
3. Require consensus for breaking changes
4. Preserve custom content not related to code changes
5. Process in order - README first, then dependent docs
6. Only modify .md files in the documented scope
7. Git-based rollback always available via git checkout

Related Skills

• /sc:git - Git operations
• /sc:document - General documentation generation
• /sc:pr-check - Pre-PR validation