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.

| # | Category | Weight | Key question | |---|----------|--------|-------------| | C1 | Diataxis Coverage | 10% | All 4 doc types present? Mode purity? | | C2 | Completeness | 12% | Public API items documented? Coverage > 80%? | | C3 | Freshness & Accuracy | 10% | Docs match current code? No stale references? | | C4 | Readability & Prose Quality | 10% | No weasel words, condescension, passive voice? | | C5 | Structure & Findability | 8% | Heading hierarchy? Scannable? No orphan pages? | | C6 | Standard Sections | 8% | Errors, params, returns, examples documented? | | C7 | Code Examples | 10% | Working, copy-pasteable, no unwrap()? | | C8 | Accessibility & Inclusivity | 6% | Alt text? Bias-free language? Global-ready? | | C9 | Inline Comments Quality | 8% | WHY not WHAT? No stale TODOs? | | C10 | Cross-references & Linking | 5% | Types linked? Related items connected? | | C11 | Testing & CI | 8% | Doc-tests? Link checking? Prose linting? | | C12 | Maintenance Process | 5% | Docs reviewed in PRs? Ownership clear? |

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

| cli-audit-doc | cli-audit-sync | |--------------|---------------| | Is the doc well-written? | Is the doc accurate? | | Quality of prose, structure, coverage | Coherence between doc and code | | "This doc comment is vague" | "This doc comment references a deleted function" |

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

Dynamic Handoffs

| Condition detected | Recommend | Why | |-------------------|-----------|-----| | Doc anti-pattern "The Lie" (docs describe nonexistent features) | /cli-audit-sync | Verify doc-code coherence | | Missing architecture explanation | /cli-forge-doc | Generate architecture docs | | README score low | /cli-forge-readme | Rewrite README | | Missing diagrams referenced in docs | /cli-forge-schema | Generate Mermaid diagrams |

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

| Skill | Relationship | |-------|-------------| | cli-audit-sync | Checks doc accuracy. cli-audit-doc checks doc quality | | cli-audit-code | Scores code quality. cli-audit-doc scores doc quality | | cli-forge-doc | Generates docs. cli-audit-doc audits existing docs | | cli-cycle | Calls cli-audit-doc as part of full project review; emit .claude/cli-audit-doc.json per ../shared/result-schema.md for orchestrator aggregation |

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

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.