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

| Layer | Style | What it checks | Severity focus | |-------|-------|---------------|----------------| | Layer 1 — Structural | lychee-style | Internal links, anchors, images, code file refs, imports | Broken refs | | Layer 2 — Semantic | DocPrism/Swimm | Module/function/type names, endpoints, CLI flags, env vars, versions | Stale names | | Layer 3 — Executable | Docs-as-Tests | Shell commands, install steps, code snippets, Mermaid diagrams, demo kits (docs/demos/**/DEMO.md: each beat's command vs its declared expected output) | Broken examples, stale demo |

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.

| Tier | Signal | Depth | |------|--------|-------| | S | 1-2 doc files | Layer 1 only + quick Layer 2 | | M | 5-15 doc files | Layer 1 + Layer 2 + sample Layer 3 | | L | 20+ doc files | All 3 layers + terminology map + diagram verification |

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

| Score | Meaning | |-------|---------| | 10/10 | Every doc reference matches code. Zero drift | | 8-9 | Minor warnings only (terminology, info-level) | | 6-7 | Some stale references but no broken commands | | 4-5 | Multiple broken references, outdated sections | | 1-3 | Documentation is actively misleading |

Integration with other cli-* skills

| Skill | Relationship | |-------|-------------| | cli-audit-doc | Scores doc quality. cli-audit-sync scores doc accuracy | | cli-audit-drift | Checks contract-code coherence. cli-audit-sync checks doc-code coherence | | cli-forge-schema | Generates diagrams. cli-audit-sync verifies existing diagrams match code | | cli-forge-readme | Generates READMEs. cli-audit-sync verifies existing README matches reality | | cli-cycle | Calls cli-audit-sync as part of the full project review; emit .claude/cli-audit-sync.json per ../shared/result-schema.md for orchestrator aggregation |

Dynamic Handoffs

| Condition detected | Recommend | Why | |-------------------|-----------|-----| | Shell commands in docs don't work | /cli-audit-shell | Audit the scripts referenced | | README architecture section outdated | /cli-forge-readme | Update README | | Stale diagrams | /cli-forge-schema | Regenerate from current code | | API reference mentions deleted functions | /cli-audit-code | Check for dead code | | Demo kit beats no longer match code (commands fail or output differs) | /cli-forge-demo | Regenerate the stale demo from the current golden path |

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Destynova2
• Source: Destynova2/cli-code-skills
• License: MIT

Install and usage instructions live in the source repository linked above.