Cli Audit Doc

---
name: cli-audit-doc
metadata:
  author: Destynova2
description: "Audit documentation quality with weighted scoring across 12 dimensions (Diataxis coverage, completeness, freshness, readability, examples, accessibility, CI testing). Detects doc anti-patterns (Wall of Text, The Lie, Jargon Soup). Use when reviewing doc quality, auditing documentation, checking for stale docs, or saying 'audit docs', 'doc quality', 'documentation review'. Invoke with an optional file or directory path."
argument-hint: "[file-or-directory]"
context: fork
agent: general-purpose
---

> **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

## Output Format

```markdown
# 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 |

## 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