# Documentation Audit

> Full audit and update of BioETL project documentation for v5.23+. Use when asked to review docs for staleness, reconcile docs with code, sync RULES.md and REQUIREMENTS.md, update architecture/provider/contract docs, reflect ADR-010/ADR-014/ADR-017, or identify dead documentation. Use when this capability is needed.

- Skill: `tomevault-io/documentation-audit-5` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/documentation-audit-5`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/documentation-audit-5/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/documentation-audit-5

---


# 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.

## 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

```bash
# 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.

---
> Source: [SatoryKono/BioactivityDataAcquisition](https://github.com/SatoryKono/BioactivityDataAcquisition) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-15 -->