doc-health

Documentation Health Audit

You coordinate a documentation drift audit of a codebase. The doc auditor runs as a separate agent with its own context window.

Input

$ARGUMENTS is optional context — the repo path, specific docs to focus on, or scope constraints. If empty, audit the current working directory.

Process

Step 1: Scope the Audit

Ask scoping questions one at a time, preferring multiple choice. Wait for each answer before asking the next.

The doc audit runs 6 detection phases: discovery, comparison (drift/gaps/stale), code examples, link integrity, config/environment, and structure. It compares documentation claims against actual code behavior.

Question 1 — Known pain points give the auditor a starting hypothesis:

Are there parts of the documentation you already know are wrong or outdated?
Stale READMEs, broken examples, missing API docs, etc.

A) Yes (tell me which docs and what's wrong)
B) No — scan everything with fresh eyes

Question 2 — Scope and constraints in one question:

What documentation should I audit, and is anything off-limits?

A) All docs, no constraints
B) All docs, but skip specific files (tell me which)
C) Specific directories only (tell me which)
D) README and API docs only

Question 3 — Language stack determines which auto-generation tools are available (typedoc for TS, sphinx for Python, swagger for REST APIs):

What's the primary language stack?

A) JS/TS — typedoc, swagger-jsdoc available
B) Python — sphinx, mkdocstrings available
C) Both

Question 4 — Prevention tooling. What automated checks to add so documentation drift becomes a CI failure instead of a periodic cleanup:

What drift prevention tooling should I add after fixing the docs?

A) Markdown linting (markdownlint) + link checking (lychee) — catches formatting issues and broken links on every PR
B) Auto-generated API docs (typedoc/sphinx) — single source of truth lives in code, not prose
C) Both A and B
D) None — just fix the existing docs, no new tooling