/docs-audit

name: docs-audit
description: Interactive documentation quality review for Mastra docs. Use when auditing, reviewing, or critiquing Mastra documentation; checking docs against source code; validating code examples, API accuracy, or property completeness; checking whether docs follow the styleguide and deterministic linters; or evaluating whether a beginner or agent can follow a doc to complete a job. This skill keeps humans in the loop with ask_user and submit_plan, then always runs an agent-build eval after approved fixes.

Documentation Audit

Audit Mastra docs against source, deterministic checks, styleguides, and followability. Produce an evidence-based report first, then an approved fix plan, then mandatory eval after fixes.

Use this for audits/reviews/critiques/accuracy checks/completeness checks/followability checks, not ordinary docs authoring.

References

Load during the audit:

• `references/RUBRIC.md`: audit dimensions and severity rules
• `references/AUDIT-REPORT.md`: required report format
• `.claude/skills/mastra-docs/references/STYLEGUIDE.md`: base docs styleguide
• One matching page-type guide from `.claude/skills/mastra-docs/references/`: `DOC.md`, `GUIDE_QUICKSTART.md`, `GUIDE_TUTORIAL.md`, `GUIDE_INTEGRATION.md`, `GUIDE_DEPLOYMENT.md`, or `REFERENCE.md`

Scripts

Use scripts for deterministic mechanics; do not hand-roll run dirs, snapshots, lint capture, eval scaffolds, typecheck logging, or local package linking. Invoke from anywhere as `bash .claude/skills/docs-audit/scripts/<name>.sh ...`.

• `init-run.sh --docs <files>`: create the temp run directory and print `RUN_DIR=...`.
• `snapshot.sh --run-dir "$RUN_DIR" --stage original|improved --docs <files>`: copy audited docs into the run dir.
• `run-checks.sh --run-dir "$RUN_DIR" --docs <files>`: run validation, repo-wide and target-scoped remark/Vale, file-scoped Prettier, and write raw output plus `$RUN_DIR/commands/summary.txt`.
• `format-doc.sh --docs <files>`: format changed docs from the docs package cwd so `docs/.prettierrc` and `docs/.prettierignore` apply.
• `eval-setup.sh --run-dir "$RUN_DIR" --job "..." --doc <file> --pkg @mastra/...`: create an eval job/project, copy `doc-under-test.mdx`, resolve local packages, and print `JOB_DIR=...`.
• `eval-typecheck.sh --job-dir "$JOB_DIR"`: run TypeScript verification and append output to `commands.log`.

Artifact policy

• Keep intermediate artifacts outside the repo in the script-created `$RUN_DIR`.
• Run `init-run.sh` before deterministic checks and report the exact printed path, including `$TMPDIR` fallbacks.
• Snapshot original docs immediately after scope confirmation; snapshot improved docs after approved fixes and before eval.
• Save `audit-report.md`, `fix-plan.md`, eval `instructions.md`, `commands.log`, and `result.md` under `$RUN_DIR`.
• Do not commit or stage temp artifacts. Keep the directory until the final response and include its path.

Required workflow

1. Scope interactively

Use `ask_user` to ask which doc page, URL/path, topic, category, or multi-page scope to audit.

DO free-text scope prompt with only `question`:

ask_user({ question: 'Which doc page should I audit? Paste a path, URL, or topic.' });

DON'T pass `options` or `selectionMode` for free text. If a free-text prompt errors with `selectionMode requires options`, you passed `selectionMode` without `options` — drop both keys and retry; do not fall back to plain chat.

Resolve to docs files under `docs/src/content/en/docs/`, `docs/src/content/en/guides/`, or `docs/src/content/en/reference/`. If ambiguous, present plausible matches. Prefer one page unless the user asks for a category. Treat more than five pages as too broad unless the user approves a narrowed scope or representative sample.

After reading scoped pages, derive 2–4 concrete jobs-to-be-done from each doc's title, intro, headings, examples, page type, and promise. Do not ask the user to invent jobs. Ask the user to select jobs with multi-select and explicit options:

ask_user({ question, options: [...], selectionMode: "multi_select" })

Only use `selectionMode` with `options`. Selected jobs seed practicability checks and mandatory eval. Confirm multi-page scope before auditing.

2. Classify page type and styleguide

Classify each scoped file before style checks:

• `docs/src/content/en/docs/**/overview.mdx`: docs overview
• `docs/src/content/en/docs/**`: docs standard
• `docs/src/content/en/guides/getting-started/**`: guide quickstart
• deployment paths or titles like `Deploy Mastra to ...`: guide deployment
• tutorial paths or titles like `Guide: Building ...`: guide tutorial
• integration paths or titles like `Using ...`: guide integration
• `docs/src/content/en/reference/**`: reference
• otherwise: other

If classification overlaps, prefer the matching frontmatter title pattern; otherwise choose by structure. Apply `STYLEGUIDE.md` plus the matching page-type guide and state the classification in the report.

3. Map docs to source

Read docs and collect frontmatter `packages:`, `@mastra/<name>` imports, mentioned APIs, `<PropertiesTable>` entries, and code-block file paths.

Resolve each `@mastra/<pkg>` import to the matching workspace `package.json`, then inspect its `exports` and `src/index.ts` before any repo-wide search. For the exact exported symbol/type, use `lsp_inspect` or `view` on the narrow export/type file first. Only broaden to `search_content` if the narrow export/type read is ambiguous.

Do not guess paths. `@mastra/core` usually maps to `packages/core/src`; `@mastra/<name>` often maps to `packages/<name>/src`, but the package `name` field is authoritative. For symbols like `cloneThread` that are noisy across tests, controllers, and docs, start from the package export surface such as `packages/memory/src/index.ts`.

Source is the source of truth for code accuracy and API completeness; never trust doc snippets at face value. If activated skill text conflict