CLI Audit Sync

Optimization: This skill uses on-demand loading. Heavy content lives in references/ and is loaded only when needed.

Language rule: Skill instructions are written in English. When generating user-facing output, detect the project's primary language (from README, comments, docs, commit messages) and produce the report in that language. If the project is bilingual, ask the user which language to use before proceeding.

Audit Sync — Documentation-Code Coherence Verifier

Detect every place where documentation says one thing and the code says another.

"A stale diagram is worse than no diagram. A README with wrong commands is worse than no README."

Core Principle

Documentation is a contract with the reader. Every statement in docs is an implicit promise: "this is true right now." This skill finds broken promises.

Gotchas — read ../gotchas.md before producing output to avoid known mistakes.

Three-Layer Verification

Read references/layers.md for detailed check tables, methodology, and safety rules per layer.

Workflow

Mitosis — Scale to doc volume

S/M/L/XL semantics are canonical in ../shared/tiering.md — the table below specializes them to doc-file count and audit-layer depth.

Step 1 — Discover documentation

Glob: **/*.md, docs/**/*, README*, CHANGELOG*, CONTRIBUTING*

Step 2 — Build code index (source of truth)

• File tree (all source files)
• Exported symbols (public functions, types, modules)
• Route definitions, config keys, CLI commands/flags
• Dependencies + version from manifest

Step 3 — Run layers (parallel)

Launch sub-agents for each applicable layer. Read references/layers.md for detailed checks per layer.

Step 3b — Duplication scan (DRY/SSOT/KISS rules)

Read references/duplication-rules.md for the 25 reproducible rules with citations (Hunt/Thomas, Fowler, Metz, McCabe, Diátaxis, SSOT).

Run 5 rule families:

• D rules — Doc-doc duplication (same paragraph/table/code block in ≥2 docs)
• C rules — Code-code cross-format duplication (Makefile + CI YAML + scripts + docs)
• S rules — SSOT violations (CLI flags, version strings, config defaults code↔doc)
• M rules — Anti-false-DRY (Sandi Metz: don't escalate < 3 instances, flag wrong abstractions)
• I rules — Information-theoretic duplication index (gzip ratio, optional)

Apply Fowler's Rule of Three: 1 = ignore, 2 = warn, 3+ = error. Exception: if 2 instances have different values (drift), it's immediately critical.

This fills a gap NO mainstream tool covers: cross-format command/env duplication detection.

Step 4 — Synthesize report

Output Format

# Doc-Code Sync Report — {project-name}

**Date:** {date}
**Files scanned:** {n} docs, {m} source files
**Coherence score:** {X}/10

## Summary

| Layer | Checks | Passed | Failed | Warnings |
|-------|--------|--------|--------|----------|

## Critical Issues (fix now)

| # | File:Line | Issue | What docs say | What code says |

## Warnings (fix soon)

## What's in sync (good)

## Terminology Map (if tier L)

Scoring

Integration with other cli-* skills

Dynamic Handoffs

Rule: Recommend, don't auto-execute.

What this skill does NOT do

• Does not fix docs — it reports. Use cli-forge-* skills to fix
• Does not execute unsafe commands — dry-run verification only
• Does not check external URLs — no network calls
• Does not replace linters — Vale/markdownlint handle prose style, this handles truth