Audit Docs
Audit documentation without changing repository or external state.
Establish Scope
- Use the user's files, directory, or migration boundary as the primary scope. Otherwise, use
docs/ when it exists.
- Include repository-level contributor or agent guidance only when it governs documentation behavior.
- Route memory directories and
MEMORY.md health checks to audit-memory unless the user explicitly includes them in a broader documentation migration.
- Do not follow symlinks outside the selected repository. Treat unavailable cross-repository provenance as a limitation, not a broken local pointer.
- 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
- 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.
- Find superseded ADRs and report living documentation that presents them as current. Do not flag historical citations that identify their status.
- 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.
- For migrations, verify whether each requested fact is present somewhere after migration. Report gaps and coverage limits; never certify losslessness.
- 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.
1---2name: audit-docs-33description: 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.4---56# Audit Docs78Audit documentation without changing repository or external state.910## Establish Scope11121. Use the user's files, directory, or migration boundary as the primary scope. Otherwise, use `docs/` when it exists.132. Include repository-level contributor or agent guidance only when it governs documentation behavior.143. Route memory directories and `MEMORY.md` health checks to `audit-memory` unless the user explicitly includes them in a broader documentation migration.154. Do not follow symlinks outside the selected repository. Treat unavailable cross-repository provenance as a limitation, not a broken local pointer.165. 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.1718## Run Deterministic Checks1920Run the bundled read-only checker before manual analysis:2122```text23python scripts/check_docs.py [scope ...]24```2526Use `--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.2728Treat 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.2930## Inspect Semantic Drift31321. 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.332. Find superseded ADRs and report living documentation that presents them as current. Do not flag historical citations that identify their status.343. 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.354. For migrations, verify whether each requested fact is present somewhere after migration. Report gaps and coverage limits; never certify losslessness.365. 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.3738## Classify and Report3940Use these severities:4142- `critical`: a broken local command, file link, required index entry, or current ADR pointer is likely to mislead contributors.43- `warning`: stale, duplicated, or ambiguous canonical documentation is likely to drift.44- `info`: a review opportunity, external provenance concern, or weak signal needs human judgment.4546For 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.4748If no finding remains after verification, say that no issues were detected in the completed checks. Do not claim that the documentation is certified correct.4950Do not edit files, regenerate indexes, stage changes, or run state-changing commands.
ValentinNikolaev