documentation-audit

name	documentation-audit
description	Audit documentation quality — inline comments, API docs, README completeness, and doc-code sync. Use when assessing whether docs are good and complete. To catch docs that have gone stale versus the code use /doc-gardening instead.
user-invocable	true

Documentation Audit

Core Rule

Audit doc-code sync and reader experience. Recommend rewrites only when current docs mislead — small fixes beat broad refactors.

When to Use

Invoke with /documentation-audit when:

• Assessing documentation quality for a project
• Preparing a project for open-source release
• Onboarding new team members and finding documentation gaps
• After major feature additions to ensure docs are updated
• Before a due diligence or code quality review

Default Behavior

When the user asks to audit, scan, review, or "give me a report" for documentation, produce the full documentation-audit report automatically using the Process and Output Format sections below. Do not require the user to specify fields.

Only modify files when the user explicitly requests implement / fix / apply / refactor. By default, this skill is report-only.

Process

Phase 1: Inventory (first-pass leads)

This pass produces candidates, not findings. Treat counts as leads for deeper inspection in later phases. Do not report Phase 1 raw output as the final result.

Catalog existing documentation:

1. README — Does it exist? Is it useful?
2. API docs — Inline docs, generated docs, API reference
3. Architecture docs — High-level design, system diagrams
4. Inline comments — Code-level documentation
5. Examples — Usage examples, tutorials, quickstart guides
6. Changelog — Version history, migration guides

Phase 2: README Assessment

Evaluate the project README:

Essential Sections

• Project name and one-line description
• What the project does (not how it's built)
• Quick start / installation instructions
• Basic usage example
• Prerequisites and requirements

Good-to-Have Sections

• Configuration options
• API overview or link to full docs
• Contributing guidelines
• License
• Status badges (build, coverage, version)

Quality Checks

• Are instructions copy-pasteable? (no placeholder values without explanation)
• Are versions/requirements current?
• Does the quick start actually work?

Phase 3: Inline Documentation

Audit code-level documentation:

Public API Documentation

• Are public functions/methods documented? (parameters, return values, exceptions)
• Are complex algorithms explained? (not what the code does, but why)
• Are non-obvious design decisions documented?
• Are edge cases and limitations noted?

Comment Quality

• Useful comments: explain WHY, not WHAT (the code says what)
• Outdated comments: comments that don't match the current code
• Redundant comments: comments that repeat what the code already says
• TODO/FIXME/HACK: are these tracked? Do they reference issues?
• Commented-out code: should be removed, not commented

Anti-patterns

• Functions with complex behavior but no documentation
• Public APIs without parameter descriptions
• Error codes/messages without explanation
• Magic numbers without explanation
• Regex patterns without explanation

Phase 4: API Documentation

If the project exposes an API (REST, GraphQL, library):

• Are all endpoints/functions documented?
• Are request/response schemas documented?
• Are error responses documented?
• Are authentication requirements documented?
• Are rate limits and pagination documented?
• Is there an OpenAPI/Swagger spec (REST) or schema file (GraphQL)?
• Are examples provided for common use cases?

Phase 5: Documentation-Code Sync

Check that docs match reality:

• Do documented APIs still exist? (no references to removed endpoints)
• Do documented config options match the actual config schema?
• Do code examples in docs actually compile/run?
• Are version references current?
• Do links in docs point to valid targets?

Output Format

# Documentation Audit Report

## Documentation Inventory
| Type | Exists | Quality | Notes |
|------|--------|---------|-------|
| README | ✅/❌ | Good/Fair/Poor | ... |
| API Docs | ✅/❌ | Good/Fair/Poor | ... |
| Inline Docs | ✅/❌ | Good/Fair/Poor | ... |
| Architecture | ✅/❌ | Good/Fair/Poor | ... |
| Examples | ✅/❌ | Good/Fair/Poor | ... |
| Changelog | ✅/❌ | Good/Fair/Poor | ... |

## Critical Gaps
1. [Undocumented public API / missing README section / outdated docs]

## Outdated Documentation
| Location | Issue | Current State |
|----------|-------|---------------|
| README line 45 | References removed config option | Option removed in v2.0 |

## Comment Quality Issues
| File | Line | Issue |
|------|------|-------|
| api/handler.ts | 23 | Comment contradicts code behavior |

## Recommendations
### Must Fix
1. ...

### Should Fix
1. ...

### Nice to Have
1. ...

## Documentation Score
[Overall: Poor / Fair / Good / Excellent]
[Key metric: % of public APIs documented]

Notes

• Good documentation explains WHY, not WHAT — the code already says what
• Don't recommend documenting everything — focus on public APIs, complex logic, and non-obvious decisions
• Over-documentation is as bad as under-documentation — redundant comments become noise
• Consider the audience: library docs need more than internal app docs