name: documenting-with-audit description: Automated documentation auditing - ensures CLAUDE.md coverage, updates stale docs, recommends structural improvements
Documentation Auditing
Knowledge for automated documentation auditing. Defines state tracking, scope system, generation templates, and output formats.
Purpose
Documentation drifts from code. This skill provides knowledge for:
- CLAUDE.md coverage in meaningful directories
- Automatic doc updates when code changes
- Freshness tracking via git commits + timestamps
- Structural improvement recommendations
State File: .docsaudit.yaml
Tracks audit state for all docs.
Format:
version: 1
ignore:
- node_modules/**
- .git/**
- dist/**
- __pycache__/**
max_age_days: 90
audits:
README.md:
commit: abc123
date: 2025-11-19T10:30:00Z
scope: ["**/*"]
src/auth/CLAUDE.md:
commit: def456
date: 2025-11-15T09:00:00Z
# No scope = directory default (src/auth/**/*)
Bootstrap: If missing, create with sensible defaults, scan existing docs, initialize with current HEAD.
Scope System
Scope = glob patterns defining which files a doc describes.
Default Scope (Automatic):
README.md(root) ->**/*(whole project)src/auth/CLAUDE.md->src/auth/**/*docs/api.md->docs/**/*
Explicit Override:
docs/api.md:
scope: ["src/api/**/*"] # Track API code, not docs dir
Independent Docs:
CONTRIBUTING.md:
scope: [] # Explicit empty = no code dependencies
Staleness Triggers:
- Files in scope changed since
commit - More than
max_age_dayssincedate
CLAUDE.md Generation
Analysis approach:
- Read directory structure and file list
- Sample code: imports/exports, class/function names, module patterns
- Check existing README/comments
- Understand purpose and relationships
Template:
# [Module Name]
## Purpose
[1-2 sentences: what this does]
## Key Components
- [file/class]: [purpose]
- [file/class]: [purpose]
## Dependencies
- Uses: [other modules]
- Used by: [other modules]
## Notes
[Important context, conventions, gotchas]
Principles:
- 2-line CLAUDE.md better than none
- Add value, avoid obvious
- Focus on non-obvious context
- Explain "why" not "what"
Examples:
# tests/fixtures/auth
JWT tokens and auth payloads for testing.
Tokens are expired but have valid structure.
# scripts/deployment
Production deployment utilities.
Run via `just deploy <env>` - never manually.
Handles DB migrations, health checks, rollback.
Coverage Decisions
Create CLAUDE.md when:
- Any meaningful code/content
- Logic, utilities, modules
- Config, data, assets needing explanation
- Test fixtures, scripts, migrations
Ignore only:
- Build artifacts (dist/, pycache)
- Dependencies (node_modules/)
- Git internals (.git/)
Sanity Check Patterns
Consolidate: >70% content overlap between docs
Move: Doc location vs scope mismatch (e.g., docs/database.md with scope src/db/**/*)
Delete: Scope patterns match zero files
Split: Doc >500 lines with multiple distinct topics
Merge: Multiple tiny docs (<50 lines each) with related scopes
Present recommendations, don't auto-apply - bigger decisions need human judgment.
Output Format
Documentation Audit Report
Coverage (CLAUDE.md files):
Created (N):
+ path/to/new.md (reason)
Un-ignored (N):
+ path/to/unignored.md (reason)
Freshness (content updates):
Updated (N):
~ path/to/updated.md (summary)
Already current (N):
✓ path/to/current.md
Recommendations:
⚠ Issue: description
⚠ Issue: description
Files changed: N
Review: git diff
Commit: git commit -am "docs: automated audit"
Symbols:
+Created/added~Updated/modified✓Already current⚠Recommendation
Default Ignore Patterns
ignore:
- node_modules/**
- .git/**
- dist/**
- build/**
- __pycache__/**
- "*.pyc"
- .pytest_cache/**
- .mypy_cache/**
- coverage/**
- htmlcov/**
Add project-specific: generated code, vendor dependencies, build outputs, IDE files.
Philosophy
Comprehensive coverage: CLAUDE.md everywhere it adds value. Even 2-line docs beat nothing. Context is cheap, confusion is expensive.
Automated maintenance: System does the work. Git provides review. Commit or revert.
Continuous improvement: Regular audits catch drift. Sanity checks improve structure. Documentation evolves with code.
Trust but verify: Automation creates/updates. Human reviews via git. Best of both worlds.