audit-docs

name	audit-docs
description	Audit repository documentation read-only for broken local links or path references, stale indexes or ADR pointers, duplicate canonical facts, migration gaps, and repository-defined language or script violations. Use for documentation-health reports; do not use for agent memory stores, source-code review, or requests to implement fixes. Report evidence only and never edit.

Audit Docs

Audit documentation without changing repository or external state.

Establish Scope

1. Use the user's files, directory, or migration boundary as the primary scope. Otherwise, use docs/ when it exists.
2. Include repository-level contributor or agent guidance only when it governs documentation behavior.
3. Route memory directories and MEMORY.md health checks to audit-memory unless the user explicitly includes them in a broader documentation migration.
4. Do not follow symlinks outside the selected repository. Treat unavailable cross-repository provenance as a limitation, not a broken local pointer.
5. Read local documentation policies before checking prohibited languages, Unicode scripts, generated indexes, or ADR conventions. Do not infer a prohibited language or script from cultural or repository context.

Run Deterministic Checks

Run the bundled read-only checker before manual analysis:

python scripts/check_docs.py [scope ...]

Use --index <index.md> --index-root <directory> only when the repository defines that file as an index. Use --prohibited-regex <pattern> or --prohibited-range <start-end> only for an explicit user or repository policy. Use --format json when structured output helps downstream analysis.

Treat checker findings as evidence to verify, not automatic conclusions. The checker deliberately excludes fenced and inline code, URLs, absolute paths, placeholders, generated or dependency directories, and prose explicitly marked as historical, external, or provenance-only. Do not report excluded content unless local policy clearly makes it load-bearing.

Inspect Semantic Drift

1. Compare declared documentation indexes with the current in-scope tree. Run only repository-provided commands explicitly documented as read-only checks; request permission if the command is unavailable under the current tool policy.
2. Find superseded ADRs and report living documentation that presents them as current. Do not flag historical citations that identify their status.
3. Identify duplicate load-bearing facts only when two independent locations claim canonical authority or can change separately. Ignore intentional summaries that point to a canonical source.
4. For migrations, verify whether each requested fact is present somewhere after migration. Report gaps and coverage limits; never certify losslessness.
5. Verify plain path references manually when context is ambiguous. Ignore examples, placeholders, generated output, external provenance, and historical references unless the repository expects them to resolve locally.

Classify and Report

Use these severities:

• critical: a broken local command, file link, required index entry, or current ADR pointer is likely to mislead contributors.
• warning: stale, duplicated, or ambiguous canonical documentation is likely to drift.
• info: a review opportunity, external provenance concern, or weak signal needs human judgment.

For every finding, include severity, file:line evidence, the affected reference or claim, and one sentence explaining impact. Group findings by audit class and include scanned scope, skipped paths, unavailable checks, and other limitations.

If no finding remains after verification, say that no issues were detected in the completed checks. Do not claim that the documentation is certified correct.

Do not edit files, regenerate indexes, stage changes, or run state-changing commands.