Validate documentation accuracy for agents — staleness, duplication, network leaks, and bloat
Audit all documentation for accuracy, staleness, duplication, and bloat. Docs are a lossy projection of the system state — this skill checks whether the projection is fresh enough for agents to trust.
Run the following audit steps and produce a summary table.
List all doc files and compute stats:
find docs papers CHANGELOG.org README.org CLAUDE.md -type f 2>/dev/null | sort
Count total files, lines, and bytes. Compare to Go source size:
wc -l main.go main_test.go
For each doc file, extract identifiers (function names, type names, field names, file paths) and verify they exist in the codebase:
# Extract potential Go identifiers from a doc
grep -oE '[A-Z][a-zA-Z]+\b' <doc> | sort -u | head -20
# Check if they exist in Go source
grep -l '<identifier>' main.go main_test.go contrib/**/*.go
Flag a doc as stale if it references:
git describe --tags --abbrev=0)conjecture_id vs cid)src/aq/*.py when Python is deprecated)For each pair of docs in the same domain, check overlap:
docs/TRANSPORTS.org vs docs/research/TRANSPORT-RESEARCH.mddocs/CHAOS-TESTING.org vs docs/research/chaos-test-plan.orgdocs/adr/WIRE-FORMAT-V3.1.md vs spec-v3-wire.orgFlag as duplicate if >50% of section headings match.
Classify each doc as one of:
aq --help, go doc, git log, or ls (delete candidate)Scan for site-specific network info that should not be in public docs:
grep -rnE '192\.168\.|nexus\.lan|hydra\.lan' docs/ contrib/ CHANGELOG.org CLAUDE.md
Flag any hits as leak.
Print a table:
=== DOC-CHECK RESULTS ===
Current version: <git describe>
Doc files: N | Doc lines: N | Go lines: N | Ratio: X:1
| File | Status | Class | Size | Notes |
|------|--------|-------|------|-------|
| docs/TRANSPORTS.org | stale | reference | 2.1K | references v0.5.0 |
| docs/research/wire-format-stress.org | ok | report | 8.4K | move to reports/ |
...
STALE: N files need updating
DUPLICATE: N pairs should be merged
DERIVABLE: N files are delete candidates
LEAKS: N files have network info
Exit with a recommendation: which docs to keep, which to merge, which to move to reports/, which to delete.