/docs-audit

name: docs-audit
description: Autonomous, report-only documentation review for Mastra docs. Use when auditing changed docs against source, validating contextual code examples or API coverage, checking canonical mastra-docs guidance, or running narrow deterministic checks.

Documentation audit

Audit Mastra documentation autonomously against source, the canonical `mastra-docs` guidance, and narrow deterministic checks. This skill is for report-only reviews. Do not edit documentation, ask the user to select jobs, or submit a fix plan unless the user separately requests implementation after the audit.

Load first

1. Activate the `mastra-docs` skill. Its references are the canonical authoring policy; do not restate their rules. 2. Read:

• `references/RUBRIC.md`
• `references/AUDIT-REPORT.md`
• `.claude/skills/mastra-docs/references/STYLEGUIDE.md`
• `.claude/skills/mastra-docs/references/INFORMATION_ARCHITECTURE.md`
• `.claude/skills/mastra-docs/references/AUTHORING_WORKFLOW.md`

3. Add the applicable canonical references:

• `/docs` pages: `DOC.md`
• `/integrations` pages: `GUIDE_INTEGRATION.md`
• `/reference` pages: `REFERENCE.md`
• pages using shared MDX or llms-txt-aware components: `COMPONENTS.md`
• pages containing Mermaid or diagram assets: `DIAGRAM.md`

Apply the verification rules in `AUTHORING_WORKFLOW.md` to every audit. Apply its move, delete, and redirect sections only when those operations are part of the reviewed diff.

Autonomous workflow

1. Determine the complete audit scope

Use the explicit files, URL, topic, or PR named by the user. Otherwise inspect the current PR/diff and include every changed authored page under:

• `docs/src/content/en/docs`
• `docs/src/content/en/integrations`
• `docs/src/content/en/reference`

Do not ask the user to choose pages or jobs. Do not silently sample or cap a large changed-page set. Exclude generated pages unless the diff changes their generator or generated contract. Record any unavailable or ambiguous scope as a report limitation instead of starting a question loop.

2. Classify every page and map canonical guidance

Use these classifications:

• `docs overview`: `/docs/**/overview.mdx` and overview-shaped `/docs/index.mdx`
• `docs page`: other authored `/docs/**` pages
• `deployment integration`: `/integrations/deploy/**`
• `integration`: other authored `/integrations/**`
• `reference`: authored `/reference/**`

Prefer content and canonical ownership when a filename is misleading. For each page, record a compliance map with its classification and every canonical reference applied. Always include `STYLEGUIDE.md`, `INFORMATION_ARCHITECTURE.md`, and the verification guidance in `AUTHORING_WORKFLOW.md`, then add the page-type, component, and diagram references that apply.

3. Plan a bounded evidence pass

Keep the audit complete without repeating work:

• Use one command over the three authored content directories to collect both the changed-file list and a focused diff. Treat changed hunks and their page-level consequences as the primary risk map; do not retry with glob variants or rerun equivalent diff commands per file.
• Read each page once in the largest practical contiguous chunks and retain its line numbers for citations. Do not separately search for code fences or reread ranges for citations; reread only when tool truncation hid required evidence.
• Do not inspect sidebars unless a sidebar changed or route ownership is genuinely ambiguous from the page path and content.
• Load each canonical reference once. Batch independent canonical-reference and page reads with `multi_tool_use.parallel`, but keep each parallel batch to at most two files and 500 requested lines so results remain directly usable. Never batch all references or all pages into one response, issue every read serially, or reread a `docs/styleguides` symlink or another alias.
• Do not create a task list for an audit-only review.
• Build one batched alternation from exact imported/exported identifiers and disputed literals across all changed pages, then search the full repository once with no context and a small per-file match cap. Omit generic words, broad option names, and already-proven prose terms so the result identifies source paths without flooding the audit. Do not guess package subtrees, begin with one search per page or symbol, or use file discovery unless that full-repository search returns no usable path.
• Group related pages, blocks, imports, and symbols into shared source reads. Once the batched search identifies source paths and line evidence, open independent implementation ranges together with `multi_tool_use.parallel`, keeping each range under 150 lines and each batch under 500 requested lines. Do not open full implementation files, issue serial source reads, or run discovery commands between the search and those reads.
• After scope, guidance, and page reads, default to no more than two focused source lookup operations per changed page. Exceed that only to resolve a material ambiguity or complete a reference surface, and batch the additional evidence.
• For guides and overviews, source-check changed claims and the code or behavior the page teaches; do not re-verify unrelated unchanged vendor behavior.
• For references, still perform the complete declared-surface comparison required below.
• Use current source and exports before history. Do not search tests or history after the exported implementation already proves the claim. Do not call an architecture expert during a docs audit: the report requires current `file:line` source evidence, and an expert response cannot replace it.
• Never call conversation recall, web search, browser tools, or external search during a repository audit. If a tool result is truncated, rerun the same repository read with narrower line ranges instead of recalling prior tool output. Repository source is authoritative for Mastra APIs and components; record any genuinely u