doc-audit

Doc Audit

Audit and maintain the documentation artifacts that make a codebase legible to AI agents. This skill is the maintenance companion to agent-ready -- agent-ready scaffolds docs, doc-audit keeps them accurate.

---

Mode Detection

Determine which mode to run based on user intent:

User Intent	Mode	Trigger Phrases
Check docs health	audit	"audit docs", "check documentation", "are docs up to date"
Fix issues	fix	"fix docs", "update documentation", "sync docs"
Full analysis + roadmap	full	"full doc audit", "doc audit with roadmap"

If intent is ambiguous, default to audit mode (read-only, safe).

---

Mode: audit (default, read-only)

No files are modified. Produces a report of findings.

Step 1: Reconnaissance

Gather codebase metadata for comparison against documentation.

Check if scripts/recon.sh exists relative to this skill's plugin directory. If available, run it. Otherwise, run equivalent inline commands:

# Project type detection
for f in package.json Gemfile requirements.txt pyproject.toml go.mod Cargo.toml build.sbt pom.xml *.csproj; do
    [ -f "$f" ] && echo "Found: $f"
done

# Find all documentation files
find . -maxdepth 3 \( -name "AGENTS.md" -o -name "CLAUDE.md" -o -name "ARCHITECTURE.md" -o -name "README.md" -o -name "CONTRIBUTING.md" \) -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null | sort

# Docs directory contents
find docs/ doc/ -type f -name "*.md" 2>/dev/null | sort || echo "No docs/ directory"

# ADRs
find . -path "*/decisions/*.md" -o -path "*/adr/*.md" -o -path "*/adrs/*.md" 2>/dev/null | grep -v node_modules | grep -v .git | sort || echo "No ADRs found"

# Top-level structure
ls -1d */ 2>/dev/null | head -20

# Source files
find . -maxdepth 4 -type f \( -name "*.ts" -o -name "*.js" -o -name "*.rb" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rs" \) -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" -not -path "*/vendor/*" 2>/dev/null | head -30

# Entry points
ls -1 src/index.* src/main.* app/main.* main.* cmd/ 2>/dev/null || echo "No standard entry points"

# Config files
ls -1 docker-compose.yml docker-compose.yaml Dockerfile .env.example .env.sample turbo.json nx.json lerna.json 2>/dev/null || echo "No config files"

# Recent git changes
git log --since="7 days ago" --name-only --pretty=format:"" 2>/dev/null | sort -u | head -20 || echo "No git history"