docs-agent-audit

Audit a docs site the way an AI agent actually consumes it, narrate the process so the user learns how agents work, and produce a ranked list of PR-sized improvements.

Core principles

• Teach while working. The user wants to understand how agents consume docs. After each logical step (not each tool call), give a one-line "here's what I did and why" so they can follow the reasoning without drowning in raw output.
• Agent-consumer POV, not stylistic review. Findings must be things that make an agent more or less likely to succeed at a real task. Grammar nits, tone, visual polish — out of scope.
• PR-sized. Every finding should map to a change one person could ship in <1 day. Rank by (impact for agents) × (ease to ship).

Workflow

1. Frame the task

Ask the user (once) for:

• The docs site URL (or confirm it from project context)
• 1–3 realistic agent tasks to evaluate against, e.g. "an agent wants to scrape a JS-rendered page and get structured JSON." If they don't have one, propose 2–3 based on the product and confirm.

Pick tasks that exercise different surfaces (quickstart, API ref, error handling, SDK install).