From doc-audit
Audits codebase documentation for accuracy, completeness, and freshness by comparing against code structure. Auto-fixes small discrepancies in fix mode, reports structural changes. Works with any language/framework.
npx claudepluginhub dgalarza/claude-code-workflows --plugin doc-auditThis skill uses the workspace's default tool permissions.
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.
Audits documentation against codebase reality across 6 phases (discovery, comparison, examples, links, config, structure), then produces remediation audit doc.
Audits markdown documentation against current codebase for accuracy, broken links, incorrect code examples, docstring coverage, and staleness. Prioritizes stale, recent, or all files.
Audits project docs for staleness, gaps, and misorganization using python scripts and haiku agents. Remediates via specialized agents with quality gate. Use after features, refactors, upgrades, or periodically.
Share bugs, ideas, or general feedback.
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.
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).
No files are modified. Produces a report of findings.
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"
Determine project pattern:
turbo.json, nx.json, lerna.json, pnpm-workspace.yaml, or package.json with "workspaces" exists, load references/patterns/monorepo.mdreferences/patterns/single-package.mdRead each dimension reference file for assessment criteria, then evaluate:
Completeness -- Read references/dimensions/completeness.md
Accuracy -- Read references/dimensions/accuracy.md
# Verify file paths from ARCHITECTURE.md
if [ -f ARCHITECTURE.md ]; then
grep -oE '`[^`]+/[^`]*`' ARCHITECTURE.md 2>/dev/null | tr -d '`' | while read -r path; do
[ ! -e "$path" ] && echo "MISSING: $path"
done
fi
# Compare ports
grep -oE '[0-9]{4,5}' docker-compose.yml 2>/dev/null | sort -u > /tmp/ports_config 2>/dev/null
grep -oE '[0-9]{4,5}' AGENTS.md ARCHITECTURE.md 2>/dev/null | sort -u > /tmp/ports_docs 2>/dev/null
diff /tmp/ports_config /tmp/ports_docs 2>/dev/null || true
Freshness -- Read references/dimensions/freshness.md
# Doc freshness
for f in AGENTS.md CLAUDE.md ARCHITECTURE.md; do
[ -f "$f" ] && echo "$f: $(git log -1 --format='%ai (%ar)' -- "$f" 2>/dev/null || echo 'untracked')"
done
# Code activity
echo "Last commit: $(git log -1 --format='%ai (%ar)' 2>/dev/null)"
echo "Commits (30d): $(git rev-list --count --since='30 days ago' HEAD 2>/dev/null)"
# New files without doc updates
git log --since="30 days ago" --diff-filter=A --name-only --pretty=format:"" 2>/dev/null | grep -v '\.md$' | sort -u | head -20
# TODOs in docs
grep -rn 'TODO\|FIXME\|HACK\|XXX' AGENTS.md ARCHITECTURE.md docs/ 2>/dev/null
Coherence -- Read references/dimensions/coherence.md
# Broken links
for doc in $(find . -maxdepth 3 -name "*.md" -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null); do
grep -oE '\[.*\]\([^)]+\.md[^)]*\)' "$doc" 2>/dev/null | grep -oE '\([^)]+\)' | tr -d '()' | sed 's/#.*//' | while read -r ref; do
dir=$(dirname "$doc")
target="$dir/$ref"
[ ! -f "$target" ] && [ ! -f "$ref" ] && echo "BROKEN in $doc: $ref"
done
done
# CLAUDE.md symlink check
if [ -L CLAUDE.md ]; then
echo "CLAUDE.md -> $(readlink CLAUDE.md)"
elif [ -f CLAUDE.md ] && [ -f AGENTS.md ]; then
echo "WARNING: CLAUDE.md and AGENTS.md both exist as regular files"
fi
# Conflicting commands
for doc in AGENTS.md CLAUDE.md README.md CONTRIBUTING.md; do
[ -f "$doc" ] && echo "--- $doc ---" && grep -E '(npm |yarn |pnpm |bundle |pip |cargo |go |make )' "$doc" 2>/dev/null | head -5
done
Read assets/audit-report-template.md for the output format.
Categorize each finding:
Present the report with specific file paths and line numbers where possible. Include concrete evidence for each finding.
Runs the full audit, then auto-fixes safe issues and reports the rest.
Execute all steps from audit mode to identify issues.
Apply safe, mechanical fixes that don't require human judgment:
For each auto-fix:
Present issues that require human judgment:
Stage and commit all documentation changes:
git add -A docs/ AGENTS.md ARCHITECTURE.md CLAUDE.md README.md
git commit -m "doc-audit: [summary of fixes]"
The commit message should summarize what was fixed (e.g., "doc-audit: update codemap paths, fix port numbers, add missing ADR to index").
Runs the full fix workflow, then generates an improvement roadmap.
Execute all steps from fix mode.
Based on the audit findings and codebase analysis, produce a prioritized improvement plan:
Priority 1 -- Accuracy fixes (misleading docs)
Priority 2 -- Coverage gaps (missing docs)
Priority 3 -- Structural improvements (better organization)
Priority 4 -- Process improvements (prevent future drift)
Present the roadmap as a numbered, actionable list. Each item should be specific enough that someone (human or agent) could pick it up and execute it.