docs-audit

name	docs-audit
description	Read-only audit of docs or README files for structural gaps, stale claims, duplication, missing content, and navigation issues. Produces an audit and rewrite plan; does not rewrite docs.

Docs Audit

Audit existing docs against their audience and purpose. Produce findings and a rewrite plan. Do not rewrite docs or edit files in this skill.

Use when

• assessing the state of READMEs, guides, or doc sites
• identifying gaps, stale content, duplication, or navigation problems
• producing a rewrite or restructuring plan
• preparing for a docs refresh

Do not use when

• the user wants docs written or rewritten
• the user wants API reference generated
• the user wants release notes

Execution model

Workflow phases:

inventory -> audience and purpose -> structural gaps -> content gaps -> severity -> rewrite plan

Audience and purpose first. Identify who each doc is for and what task it should support. A README that targets new users is a different doc from one targeting contributors. Findings only make sense relative to audience and purpose.

Cite every finding. Each finding names the file or section it refers to. Findings without a citation are noise.

Severity, not adjectives. Use severity (critical, major, minor) tied to user impact, not subjective adjectives ("messy", "boring").

Hard rules

• Read-only: do not edit, create, delete, or rewrite files.
• Cite files or sections for every finding.
• Do not rewrite docs; produce an audit and a rewrite plan only.
• Tie findings to audience and purpose, not to personal style preference.
• Do not invent claims about content that was not inspected.
• Mark "possibly stale" claims as unverified unless source code or release notes confirm.
• Works standalone; does not require any companion prompt.

Artifact format

Use only sections that matter.

docs-inventory: files reviewed, approximate sizes, last-modified dates if visible.

audience-and-purpose: per major doc, who it serves and what task it supports.

structural-gaps: missing sections, wrong ordering, missing prerequisites, weak onramps.

missing-pages-or-sections: topics absent from the doc set; cite where they would belong.

stale-or-unsupported-claims: claims that look out of date or are unsupported by code/releases; mark confirmed or unverified.

duplication: overlapping content across pages; consolidation candidates.

navigation-issues: discoverability problems, broken or unclear links, missing index or TOC.

severity: per finding (critical|major|minor) with user-impact reasoning.

recommended-rewrite-plan: ordered set of changes; estimated scope per change; what would be a quick win vs deeper work.

Response format

End each response with: scope, confidence (high|medium|low), status, key assumptions or what was not inspected, next-step (only if useful).