---
name: docs-audit
description: Audit and rebuild software-repository documentation against implementation evidence. Use for comprehensive documentation audits or refreshes that may create, rewrite, move, merge, or delete README files and project documentation; reconcile documentation with code, tests, configuration, commands, and public interfaces; redesign documentation structure; update documentation tooling; and add evidence-backed Mermaid diagrams. Do not use for small copy edits, repository-only analysis, or application-code changes.
---

# Docs Audit

Audit the implementation before editing its documentation. Produce the clearest evidence-backed documentation set even when that requires replacing the existing structure rather than preserving it.

## Honor the authority and its boundaries

- Derive editing authority from the user's request. A broad request to audit, rebuild, refresh, or comprehensively update project documentation authorizes creating, rewriting, renaming, moving, merging, and deleting in-scope documentation without approval for each operation. Keep narrower documentation requests within their requested scope; automatic skill selection alone never expands the user's authorization.
- Include root and nested READMEs, documentation source trees, Markdown, MDX, reStructuredText, and AsciiDoc guides, contributor and operator guides, documentation-owned examples, and documentation-specific navigation, configuration, dependencies, scripts, and lockfile entries.
- Keep application source, tests, schemas, runtime configuration, and product dependencies read-only. Change shared manifests, scripts, or lockfiles only for entries required by documentation tooling; do not alter application behavior.
- Protect `LICENSE`, `NOTICE`, attribution files, `SECURITY`, `CODE_OF_CONDUCT`, changelogs, and accepted ADRs unless the user explicitly names them for modification. Read them when they constrain the documentation.
- Inspect the worktree before editing. Preserve unrelated changes and user-authored uncommitted work. Stop for direction when an intended documentation rewrite overlaps changes that cannot be retained safely.
- Never expose credentials, private data, unpublished vulnerabilities, or sensitive repository content in examples or generated documentation.
- Do not publish, commit, push, release, or modify external systems unless the user separately requests that action.

## Establish repository truth

1. Read every applicable `AGENTS.md` from the repository root through each documentation or tooling subtree that may change.
2. Identify the repository's primary language, audiences, configured documentation root, documentation toolchain, and existing navigation. Preserve an established language; ask only when the repository is genuinely mixed or unclear.
3. Inspect manifests, entrypoints, exported interfaces, routes, schemas, configuration, CLI help, tests, CI, packaging, deployment, examples, and useful history. Treat current code, tests, and verified runtime results as stronger evidence of behavior than existing prose.
4. Inventory all documentation and repository references to it, including links from source comments, package metadata, CI, issue templates, and documentation configuration.
5. Map the documented surface against the implemented surface: purpose, supported capabilities, prerequisites, installation, configuration, usage, public interfaces, architecture, data flow, persistence, operations, testing, troubleshooting, privacy, security, support, and lifecycle where applicable.
6. Run safe, repository-discovered commands when they materially verify a claim. Never invent commands or use a networked service merely to make a claim appear verified.

## Control evidence and uncertainty

Classify each existing document or substantial section and record a concise reason:

- `keep`: accurate, well placed, and useful as written.
- `rewrite`: needed in the same canonical location but inaccurate, unclear, or poorly structured.
- `merge`: unique material should move into another canonical document before this copy is removed.
- `move`: content is useful but belongs at a better path or information boundary.
- `create`: an implemented, user-relevant surface lacks documentation.
- `delete`: redundant, obsolete, misleading, empty, or no longer useful after consolidation.
- `research-gated`: its correct treatment depends on evidence or product intent that is not available.

Use claim states only for consequential assertions:

- `verified`: directly supported by code, tests, configuration, command output, or authoritative external material.
- `stale`: describes behavior or structure that has demonstrably changed.
- `unsupported`: lacks evidence and should not be presented as fact.
- `conflicted`: credible sources disagree in a way that affects the documentation.
- `missing`: implemented behavior needs documentation but has no adequate coverage.

Do not convert an undefined product rule, aspirational comment, failing test, or ambiguous code path into promised behavior. Ask the user when a material conflict represents unresolved intent; continue with independent documentation work when safe.

## Rebuild the information architecture

- Respect a coherent documentation root already selected by active tooling or repository convention. Create root `docs/` only when no established documentation source exists.
- Ensure the repository ends with a root `README.md`. Keep it text-first and concise: purpose, supported capabilities, prerequisites, quick start, minimal usage, documentation navigation, verification or help links, status, and licensing only when evidence supports them.
- Organize focused documentation around reader tasks and stable concepts rather than mirroring the source tree. Create only the pages the project needs, such as architecture, configuration, workflows, public interfaces, operations, testing, or troubleshooting.
- Give each fact one canonical home. Replace duplicated explanations with relative links that work both on GitHub and in a local clone.
- Preserve valuable content before removing its old file. Delete obsolete or redundant documents after their unique material and inbound references have been handled.
- Do not retain backup, legacy, or superseded copies when version control already provides recovery.
- Update navigation, tables of contents, cross-references, package metadata, CI paths, and documentation-site configuration whenever paths or headings change.

## Use Mermaid deliberately

- Put Mermaid diagrams only in focused architecture, workflow, lifecycle, or data documentation. Keep Mermaid out of README.
- Require at least one focused diagram when repository evidence shows multiple components, boundaries, states, or workflow steps. Do not invent architecture or add a decorative diagram to a genuinely trivial project.
- Choose the smallest useful form: flowchart for boundaries or data flow, sequence diagram for interactions, state diagram for lifecycle behavior, and entity relationship diagram only for evidenced data relationships.
- Use fenced `mermaid` blocks compatible with GitHub rendering. Use stable identifiers, quote labels containing punctuation, keep diagrams readable at normal width, and avoid encoding meaning through color alone.
- Add adjacent prose that explains the diagram's purpose, boundaries, and important relationships so the document remains understandable without the rendered graphic.
- Validate syntax with existing project tooling when available. Introduce the smallest project-appropriate documentation check only when it provides durable value; do not add a full documentation platform solely to render one diagram.

## Change documentation tooling carefully

- Prefer the repository's current documentation stack and conventions when they remain coherent.
- Add, replace, or configure documentation-only tooling when necessary to keep navigation, links, examples, builds, or Mermaid rendering verifiable.
- Keep documentation dependencies and scripts clearly separated from product dependencies where the ecosystem permits it. Update the appropriate lockfiles and documented commands together.
- Edit generated documentation at its authoritative source or generator rather than patching generated output. If the required generator change would alter application code, leave that change out of scope and report the blocker.
- Follow host approval requirements for downloads, package installation, network access, or external services. Never bypass an unavailable check by silently weakening the documentation claim.

## Verify the result

1. Re-read every changed document and its surrounding navigation as a reader would.
2. Run repository-discovered documentation builds, Markdown checks, link checks, Mermaid checks, example compilation, CLI help, tests, or builds needed to verify documented behavior. Prefer targeted checks, then run the documented full suite when it is safe and practical.
3. Verify relative links, anchors, moved paths, commands, filenames, configuration keys, public symbols, version claims, and diagram relationships against repository truth.
4. Search the entire repository for retired paths, stale headings, obsolete terminology, duplicated canonical explanations, and references to deleted files.
5. Review the final diff for accidental application changes, protected-file changes, sensitive data, malformed Markdown, and whitespace errors. Use `git diff --check` when Git is available.
6. If a check is unavailable, unsafe, failing for a pre-existing reason, or requires unapproved external access, preserve the limitation in the handoff instead of claiming success.

## Return the handoff

Report:

- the final documentation structure and the audience or purpose of each major document;
- files created, rewritten, moved, merged, and deleted;
- documentation-tooling changes, if any;
- the authoritative repository evidence used for consequential corrections;
- validation commands and their results;
- unresolved, conflicted, or unverified claims and what would resolve them;
- protected files intentionally left unchanged; and
- the repository-wide stale-reference search result.