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

• DISCOVER - Run git diff or git log to find changed files

• ANALYZE - Read changed files, categorize by type (API, config, deps, features)

• MAP - Match changed files to affected documentation using source-of-truth mapping

• VALIDATE - Cross-reference consistency checks across all docs

• PLAN - Identify sections needing updates, generate staleness report

• GENERATE - Update documentation sections via Edit tool

• VERIFY - Review final docs with PAL codereview

Flags

Flag Type Default Description

--base

string main

Base branch to compare against

--preview

bool false Preview changes without writing

--consensus

bool false Force PAL consensus for all updates

--scope

string readme Target: readme , all , or custom doc paths

--commits

int

Analyze N recent commits instead of branch diff

--report-only

bool false Generate staleness report without changes

--cross-ref

bool true Enable cross-reference validation

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

Category File Patterns Affected Docs

API *.py , *.ts , *.js with new exports README, API docs

Dependencies package.json , requirements.txt , pyproject.toml

README, Installation

Config .env* , .config. , settings.*

README, Config docs

Features New modules, significant additions README, Feature docs

Database models/ , migrations/

Database docs, README

Frontend src/components/ , src/pages/

Frontend docs, README

Infrastructure docker-compose* , Dockerfile , CI configs DevOps docs, README

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:

Doc File Purpose

README.md

Main project documentation

CLAUDE.md

Claude Code instructions

CONTRIBUTING.md

Contribution guidelines

docs/*.md

Extended documentation

frontend/README.md

Frontend-specific docs

api/README.md

API documentation

Source-of-Truth Mapping

Map code changes to affected documentation:

Code Pattern Affected Documentation

src/api/** , app/routers/**

README, API docs

src/models/** , app/models/**

README, Database docs

src/components/** , frontend/src/**

README, Frontend docs

migrations/**

Database docs

.env.example

README, all docs with env references

tests/**

README (test structure section)

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:

• README.md first (primary reference)

• CLAUDE.md second (must stay consistent with README)

• 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

• Back up docs before modifications

• Never remove sections without user confirmation

• Require consensus for breaking changes

• Preserve custom content not related to code changes

• Process in order - README first, then dependent docs

• Only modify .md files in the documented scope

• 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