name	documentation-audit
description	Run a recurring documentation audit for this repo after several development cycles. Use when the user asks to audit docs, tighten documentation, recover from doc drift, do post-cycle documentation cleanup, or verify that docs still match code, infra, workflow, and live operating reality. Audit docs/, STATUS.md, README.md, and infra.example.yaml. Return findings first, then apply fixes.

Documentation audit

Audit documentation for drift. Do not do broad prose cleanup. Use the dedicated agent-surface-audit skill for .claude/ surfaces and other repo-shared AI operating instructions.

Setup (always first)

Before reading any files or auditing anything:

Create a Linear ticket using mcp__linear__save_issue:
- team: Finance Intelligence
- title: Documentation audit — <YYYY-MM-DD>
- description: three sub-bullets matching the audit scope (drift scan, fix in-place, commit)
- state: Todo
- priority: 3 (Medium)
Create a feature branch from the current dev:
```
git checkout dev && git pull && git checkout -b fin-<id>-documentation-audit
```
Use the issue ID returned by Linear (e.g. fin-154).

Do not start reading files until both steps are complete.

Scope

Default scope:

docs/
STATUS.md
README.md
infra.example.yaml

If the user narrows scope, still verify cross-references into skipped files before declaring a document correct.

Read first

Always read:

STATUS.md
docs/INDEX.md
docs/reference/CONVENTIONS.md
rg --files docs

Read on demand:

docs/architecture/ARCHITECTURE.md for topology, ownership, runtime shape
docs/architecture/DECISIONS.md before calling a design choice drift
docs/operations/TESTING.md for fixture and test-status claims
current code, routes, scripts, workflows, and config files when docs make operational claims

If a claim is supposed to match live infrastructure rather than repo state, verify the live source before editing the doc.

Checklist

Accuracy

topology, IPs, CT IDs, RAM, and placement match infra.example.yaml or verified live state
service ownership and runtime location match current architecture and deploy shape
routes, script paths, commands, DAG names, and ports match the repo
node4 is treated as the Windows workstation, not a cluster node

Completeness

major flows have a clear owner and runtime location
setup and workflow docs still cover the path they claim to cover
testing docs reflect the actual current test and fixture surface
non-obvious design rules referenced in docs are either in DECISIONS.md or clearly enforced elsewhere

Duplication

stable facts live in one canonical place
STATUS.md contains only session-specific facts, blockers, decisions, and next actions

Broken references

markdown links resolve
docs/INDEX.md points only to real files
references to scripts, workflows, and repo files match current paths

Noise

remove stale timeline language, hedging, and implementation-history asides
remove sections that restate obvious code behavior
keep STATUS.md under 80 lines

Finding types

Classify each finding before editing:

factual drift
procedural drift
duplication
dead reference
scope noise

Fix location rules

update the skill when the missing piece is repeatable procedure
update repo docs when the missing piece is factual or canonical-location drift
update code, tests, or hooks when the problem is enforceable

Do not add one-off repo facts to the skill.

Output

Report findings first, in severity order.

For each finding include:

file
defect type
incorrect claim or problem
source of truth
action taken or required

If no findings remain, say so explicitly and note any residual risk, such as:

live infra not re-verified
historical release notes intentionally left untouched
deferred blockers outside documentation scope

Guardrails

do not rewrite docs for style alone
do not call a design choice drift before reading docs/architecture/DECISIONS.md
do not move stable facts into STATUS.md
do not treat historical release notes as active operational docs unless explicitly scoped in

Maintenance rule

After each real audit, ask:

What repeatable part of documentation recovery or cleanup did the agent still have to improvise?

If the answer is procedural and likely to recur, update this skill. If the answer is factual, update the relevant repo doc instead.

name	documentation-audit
description	Run a recurring documentation audit for this repo after several development cycles. Use when the user asks to audit docs, tighten documentation, recover from doc drift, do post-cycle documentation cleanup, or verify that docs still match code, infra, workflow, and live operating reality. Audit docs/, STATUS.md, README.md, and infra.example.yaml. Return findings first, then apply fixes.