documentation-audit

Documentation Audit

Objective

Perform a full documentation audit of BioETL and bring docs in sync with code and ADRs (v5.23+). Produce a clear audit report, a prioritized plan, and updated documentation changes.

Source Of Truth

• Root runtime contract: ../../../AGENTS.md
• Project rules: ../../../docs/00-project/RULES.md
• Requirements: ../../../docs/01-requirements/REQUIREMENTS.md
• Accepted ADRs: ../../../docs/02-architecture/decisions
• Normative index: ../../../docs/00-project/NORMATIVE_SOURCES.md

Required inputs (before starting)

• Load references/audit-checklist.md — checklist for each audit area.
• Load references/report-template.md — template for the audit report.
• Treat ../../../AGENTS.md, ../../../docs/00-project/ai/agents/guides/MEMORY_USAGE.md, and ../../../docs/00-project/ai/agents/policy/POST_CHANGE_VALIDATION.md as the active runtime policy entrypoints for AI-surface documentation work.

Workflow

1. Intake and scope

• Confirm repo root and target version (v5.23+).
• Identify doc entry points: README.md, mkdocs.yml.
• List files under docs/: rg --files docs.

2. Audit (follow audit-checklist.md)

• Compare documentation to current code and configs.
• Focus: RULES.md, REQUIREMENTS.md, architecture, provider, contract docs.
• Check ADR alignment: ADR-010 (Local-Only), ADR-014 (Determinism), ADR-017 (Observability).
• Trace doc claims back to runtime/code/config/workflow sources and note mirror surfaces when AI guidance files are involved.
• Record findings with severity: Critical, High, Medium, Low.

3. Plan

• Turn findings into a concrete change list.
• Prioritize by impact (Critical > High > Medium > Low).
• Call out unknowns that need user confirmation.

4. Update (if user requests)

• Edit docs to match current code and ADRs.
• Keep versions and dates explicit in text.
• For obsolete docs: propose delete/archive, do not remove unless user asks.

5. Verify

• Check links and nav entries (mkdocs.yml).
• Confirm RULES.md and REQUIREMENTS.md are synchronized.
• Ensure ADRs are reflected in top-level docs.
• When AI runtime/docs surfaces were touched, verify runtime source first and mirror consistency second.

Practical commands

# ADR references
rg -n "ADR-010|ADR-014|ADR-017" docs README.md mkdocs.yml

# Version mentions
rg -n "v5\.23|5\.23" docs README.md

# Doc refs in nav
rg -n "docs/|\.md" mkdocs.yml README.md

# Orphan scan: list docs/ then search each filename in mkdocs.yml and other docs
rg --files docs

Output format

• Use references/report-template.md structure for the audit report.
• Provide a short prioritized change list and required user decisions.
• Do not change code unless explicitly requested; focus on documentation.

Constraints

MUST

• Use report-template.md for the audit report.
• Verify findings against actual code and configs.
• Record severity for each finding.

MUST NOT

• Change code unless user explicitly asks.
• Remove docs without explicit user approval.
• Document desired behavior instead of reality when code and docs diverge — flag and propose options.

SHOULD

• Prefer documenting reality; when code and docs diverge, flag and propose options.