oma-docs - Documentation Drift Detector

oma-docs - Documentation Drift Detector

Scheduling

Goal

Detect broken references in repo markdown — default glob **/*.md (verify mode), propose LLM-generated patch proposals for docs affected by recent code changes (sync mode), detect structural drift between English source docs and their translations (i18n mode), and lint translated docs for CJK style anti-patterns (lint mode). All modes run on-demand; sync is always interactive.

Intent signature

• User asks to check if docs are up to date, find broken doc links, verify file paths referenced in docs, or detect documentation drift.
• User asks to update docs after a code change, propose doc patches for a git diff, or sync affected docs.
• User asks whether translations are stale, which i18n docs drifted from the English source, or to lint translated docs for style issues (em-dashes in CJK targets, etc.).
• A workflow hook checks docs.auto_verify: true and runs oma docs verify --json at completion.

When to use

• After a refactor, rename, or file deletion, to find stale references in docs.
• Before a release, to confirm that CLI commands, file paths, and config keys in docs still exist.
• After a significant git diff, to discover which docs reference the changed files and may need updating.
• After updating English source docs (web/docs), to find translations (web/i18n/{lang}/...) that drifted or went missing.
• Before a docs release, to lint CJK translations for content-level anti-patterns.
• Routine drift check on any docs-heavy repo.

When NOT to use

• Generating docs from scratch for undocumented features → v2 create mode.
• Actually translating or restructuring docs → use oma-translation (oma docs i18n / oma docs lint only detect; they never edit translations).
• Symbol-level semantic drift (function signature changes not reflected in prose) → v2 L3 mode.
• CI-blocking enforcement → v2 block mode (v1 is warn-only).
• Explaining a code change as an educational document → use oma-explanation (this skill detects drift; it does not author explainers).

Expected inputs

verify mode: Optional glob path (default **/*.md), optional --json flag, optional --report-file <path>.

sync mode: Optional git diff range (default --cached, fallback HEAD~1..HEAD).

i18n mode: Optional --min-severity <CRITICAL|HIGH|MEDIUM|LOW> (default MEDIUM), optional --json.

lint mode: Optional --locales <list> (comma-separated CJK locales for the cjk-em-dash rule, default ko,ja,zh), optional --json. The default wrong-language rule always scans every locale under web/i18n/ and is not narrowed by --locales.

Expected outputs