Documentation Auditing

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:

1. Files in scope changed since commit
2. More than max_age_days since date

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.