Skip to main content

Docs Page Auditor Agent

The Docs Page Auditor is a custom Cursor agent that reviews any markdown page in this workspace, gathers context from linked docs, and writes an audit + proposed updated draft into a queue for human approval.

It never edits source files directly.

Workspace: Full (TechStackMain) · MCP: None

Purpose​

  • Enforce existing content rules consistently across docs.
  • Check that a page is still accurate and well-linked.
  • Propose a clean, updated .md version that can be approved or rejected.
  • Keep a written audit trail for each change.

Source and Configuration​

  • Agent definition: .cursor/agents/docs-page-auditor.md
  • Queue folder: .cursor/plans/docs-agent-queue/

The agent loads core content rules and Docusaurus conventions before auditing:

  • docusaurus/docs/prompts/development/content-editing.md
  • docusaurus/docs/docusaurus/index.md
  • docusaurus/docs/docusaurus/repo-structure.md
  • docusaurus/docs/docusaurus/features/callout-component.md
  • docusaurus/docs/docusaurus/features/faq-structured-data.md
  • docusaurus/docs/tools/design-content/mermaid.md
  • Relevant templates in docusaurus/docs/docusaurus/templates/*.md

Source-of-Truth Rules​

The auditor must respect the source-of-truth locations:

  • Tool docs

    • Source: tools/<tool>.md
    • Generated: docusaurus/docs/tools/... (never edited directly)

  • Script docs

    • Source: scripts/resources/<tool>/README.md (and any sibling .md with title: frontmatter)
    • Generated: docusaurus/docs/scripts/... (never edited directly)

  • Custom Docusaurus pages

    • Source: docusaurus/docs/**/*.md (except generated tools/scripts output)

If you point the auditor at a generated page, it maps to and audits the underlying source file.

Queue Outputs​

For every run, the auditor writes:

  • Audit report
    .cursor/plans/docs-agent-queue/audits/<YYYY-MM-DD>/<slug>--audit.md

  • Proposed draft
    .cursor/plans/docs-agent-queue/drafts/<YYYY-MM-DD>/<slug>--proposed.md

The audit report includes findings by severity and a full proposed updated markdown block. The draft file contains only the updated markdown content.

Typical Workflow​

  1. Run the auditor on a target page.
  2. Review the audit report and proposed draft in .cursor/plans/docs-agent-queue/.
  3. If approved, hand off to the Docs Page Fixer with the approved draft path and source file path.