CLI Audit Doc

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 Doc — Documentation Quality Index (DQI)

"Stale docs are worse than no docs." — Docs-as-Tests methodology

Core Principles

1. Evidence-based — every finding needs a file:line reference
2. Read the code — verify docs match implementation. Stale docs are the #1 problem
3. Diataxis-aware — classify each doc by type (tutorial, how-to, reference, explanation) and check mode purity
4. Language-specific — apply each language's idiomatic doc conventions (see reference.md for language-specific rules)
5. Public API first — public items are priority. Private items are nice-to-have
6. Gotchas — read ../gotchas.md before producing output to avoid known mistakes

Input

$ARGUMENTS is the target to audit (file path, directory, or empty for whole src/).

• If a specific file: audit that file deeply
• If a directory: audit all source files in it
• If empty: audit src/ (or project root) broadly (sample 15-20 key files)

First, detect the primary language(s) from file extensions. Consult reference.md for language-specific conventions.

12-Dimension Framework

Score each dimension 0.0-1.0, then compute a weighted DQI. Read references/categories.md for detailed check lists per category.

Workflow

Step 1 — Discover and sample

Glob source and doc files. For broad audit: sample public API modules, README, docs/ directory, and most-changed files.

Step 2 — Detect language and conventions

Identify project language, then load reference.md for language-specific doc conventions (Rust: RFC 1574 + rustdoc, Python: PEP 257, JS/TS: JSDoc/TSDoc, Go: godoc).

Step 3 — Score all 12 dimensions

Read references/categories.md for detailed checks. For each category: collect evidence, assign score 0.0-1.0, note specific file:line findings.

Step 4 — Compute DQI and detect anti-patterns

Read references/scoring.md for the DQI formula, Doc Debt Score, maturity level mapping, named anti-patterns, and comparative benchmarks.

DQI = Σ(wᵢ × sᵢ) / Σ(wᵢ) × 10

Step 5 — Generate report

Finding tier and confidence semantics are canonical in ../shared/triage.md (Tier 3/2/1 + GRADE + triangulation). D-dimension findings carry tier and confidence so cli-cycle can aggregate without re-parsing.

Output Format

# Documentation Quality Audit — {project-name}

**Target**: [file/directory] | **Language**: [detected] | **Date**: [date]
**DQI Score**: X.X/10 — {verdict} | **Doc Debt**: X% ({color})
**Maturity Level**: {1-5} — {name}

## Scores by Category

| # | Category | Weight | Score | Weighted | Findings |
|---|----------|--------|-------|----------|----------|
| C1-C12 rows with 0.0-1.0 scores... |
| | **DQI** | **100%** | | **X.X/10** | |

## Anti-Patterns Detected
| Pattern | Severity | File:Line | Recommendation |

## Critical Violations (must fix)
### [Category]: [violation title]
- **File**: `path/to/file:123`
- **What**: [description]
- **Rule**: [which standard it violates]
- **Fix**: [concrete suggestion]

## Good Practices Found
[positive reinforcement]

## Recommended Next Steps
1. [highest-impact fix first]

Boundary with cli-audit-sync

Both complement each other. Run cli-audit-doc for quality, cli-audit-sync for accuracy.

Dynamic Handoffs

Rule: Recommend, don't auto-execute.

What this skill does NOT do

• Does not fix docs — it reports. Use cli-forge-doc to generate documentation
• Does not check doc-code coherence — use cli-audit-sync for that
• Does not replace Vale/markdownlint — it complements them with semantic analysis
• Does not audit code quality — use cli-audit-code for that

Integration with other cli-* skills

Reference Sources

• Procida — Diataxis framework | Bhatti et al. — Docs for Developers | Martraire — Living Documentation
• Google Dev Docs Style Guide | Microsoft Writing Style Guide | RFC 1574 (Rust)
• Vale linter (prose quality) | lychee (link checking) | markdownlint | Spectral (OpenAPI)
• Write the Docs Podcast | I'd Rather Be Writing (Tom Johnson) | Knowledgebase Ninja