doc-audit

Doc Audit

Overview

This skill audits a documentation folder and produces a single prioritized report of quality problems. It checks four independent dimensions, confirms each finding is real, and groups the results by severity.

When to use

Use when the user asks to audit documentation, check docs quality, or do a pre-release docs pass on a folder of Markdown/MDX files.

Procedure

Step 1 — Inventory

List every documentation file under the target folder (default: ./docs). Record the relative path and size of each .md / .mdx file. If there are no docs, stop and report that.

Step 2 — Audit the four dimensions

For the inventory, check these four dimensions. They are independent — none of them depends on the result of another:

1. Broken links — find internal links that point to missing files/anchors and external links that look dead or malformed.
2. Stale code examples — find fenced code blocks that reference APIs, flags, or file paths that no longer exist in the project.
3. Missing sections — compare each page against the expected shape for its type (a how-to needs prerequisites + steps; a reference needs a parameter table) and list missing sections.
4. Readability — flag pages with overlong paragraphs, undefined jargon, or a reading level inappropriate for the audience.

For each dimension, produce a list of findings. Each finding has: file, a short title, a severity (blocker / major / minor), and a suggested fix.

Step 3 — Verify each finding

Documentation audits produce false positives (a "broken" link that is actually valid, a "stale" example that still works). Before reporting, confirm each finding is real by re-checking it against the actual files. Drop findings that do not hold up.

Step 4 — Prioritize and report

Merge the confirmed findings from all four dimensions, de-duplicate any that overlap, sort by severity (blockers first), and write a single DOC-AUDIT.md report grouped by dimension with a summary count at the top.