Doc audit contributor

Documentation Content Audit → Quick Contribution Finder

Purpose

Find a handful of real, defensible documentation content problems, fast, so they can become quick GitHub issues/PRs — real merged contributions, not busywork. The workflow stays clean and easy to follow step by step: page by page, clear reasoning, clear output, no wandering — so it's just as easy to demo/watch as it is to run.

This skill only looks at documentation CONTENT — not the website itself.

In scope (the only things to look for)

• Code examples that are actually broken — wrong import, wrong parameter/method name, syntax error, missing required step, code that would fail if run as written.
• Missing code/setup — an example skips something the reader needs (an import, an env variable, an install step) to make it actually work.
• Unclear / confusing explanation — wording that would genuinely mislead or confuse a newcomer trying to follow the doc.
• Missing information — a documented function/concept that leaves out something important a reader needs (e.g. no mention of a required parameter, or an exception that isn't documented).

Out of scope (never report these)

• Website navigation, sidebar/dropdown click behavior, "wrong page opens when I click X"
• Broken links, 404s, redirects
• Button vs <a> tag semantics, accessibility/ARIA issues
• Icons, images, CDN errors, console network errors
• Capitalization, spacing, visual styling, layout

If something in this "out of scope" list catches your eye, ignore it and move on — it is not the point of this skill.

Step 0 — Confirm scope (fast)

1. Target: which docs site (e.g. "OpenAI Agents SDK Python docs"). If the user just names a project, find the docs root via a quick search.
2. Depth: default to 5–8 pages for a fast first pass — prioritize Getting Started / Quickstart and the most-used API reference pages. Small and fast beats broad and slow; the goal is a quick real finding, not total site coverage. Do more only if asked.
3. Source repo (if easy to find, e.g. via an "Edit this page" link): useful for a fast sanity-check of code examples, but don't spend long hunting for it — if it's not obvious in under a minute, skip this and rely on internal consistency checks instead (see Step 3).

Don't ask more than one clarifying question — assume sensible defaults and say what you assumed, then get moving.

Step 1 — Pick the pages

1. Navigate to the docs root, snapshot the nav to see real page titles.
2. Pick the 5–8 highest-value pages: Quickstart/Getting Started first (most readers hit this, so a bug here is the most valuable find), then 1–2 core API reference pages.
3. Tell the user the page list in one line before starting, so they can redirect if needed — then go.

Step 2 — Read each page's content (not its UI)

For each page:

1. Navigate to it, take a snapshot/extract the rendered text and every code block.
2. Read the code examples like you're a beginner actually about to run them: are all imports shown? Is every variable used actually defined somewhere above? Would this run top-to-bottom as written?
3. Read the prose around each example: does it tell the reader what to do in the right order? Is any step assumed but never stated?
4. Ignore everything about how the page looks, links, or the sidebar.

Step 3 — Verify before reporting

This is what makes a finding real instead of a guess:

• Code issues: if you have the source repo, do one quick check (open the relevant source file, confirm the method/parameter name). If you don't have easy repo access, check for internal consistency instead — e.g. does the code use a class/import that's never introduced anywhere earlier in the same docs? That alone is often enough to be confident without needing the source repo.
• Confusing explanation: be able to state exactly which sentence/step is the problem and what a reader would actually get stuck on — not just "this feels unclear."
• If you can't verify something confidently, mark it "unconfirmed" and move on rather than including it as a claim.

Step 4 — Turn each finding into a ready-to-submit PR package

Don't stop at "here's the problem." For every finding, directly generate:

1. Branch name: docs/<short-kebab-case-description> — e.g. docs/fix-missing-import-quickstart, docs/clarify-auth-setup-steps. Keep it under ~50 characters, descriptive enough that a maintainer knows what it touches without opening the diff.

2. Commit message (Conventional Commits style, widely recognized): docs: <imperative, present-tense summary> — e.g. docs: fix missing import in agents quickstart example.

3. PR title: same style as the commit message, specific enough to read clearly in a PR list — not just "fix docs".

4. PR description — fill this in for every PR:

   ## What
   <one or two sentences: what was wrong, exactly>
   
   ## Why
   <the evidence — e.g. "running this example as-written raises
   ImportError because X is never imported" or "the docs describe
   parameter Y which no longer exists in vX.X, see <source link>">
   
   ## Fix
   <what this PR changes, in plain terms>
   
   ## Verification
   <how you confirmed it — ran the example locally, checked the source,
   etc.>
   

5. Keep each PR to ONE fix. A PR that fixes one clear thing gets reviewed and merged far faster than one that bundles several unrelated changes.

6. Tone: direct and proof-first — state the problem, show the evidence, propose the fix. No filler.

Generate this directly from what you already found — don't browse the repo further to check contribution guidelines or existing issues/PRs, that belongs to the user's own judgment before submitting, not this step. Present the full package (branch name, commit message, PR title, description) right alongside each finding so the user can go from "here's the audit" to "here's the exact PR to open" in one step.

Step 5 — Output (fast, clean, demo-friendly)

For each finding:

### <page title> (<url>)
**Type:** Broken code | Missing setup step | Unclear explanation | Missing info
**Problem:** <one or two sentences, precise>
**Why:** <the check that confirms it>
**Fix:** <the concrete correction>

**Branch:** <branch name>
**Commit message:** <commit message>
**PR title:** <PR title>
**PR description:**
<the What / Why / Fix / Verification template, filled in>

Then a short priority line: which 1–2 findings are the fastest to turn into a PR right now (e.g. a one-line code fix) vs. which are worth an issue first (e.g. a missing section that needs a maintainer's OK before writing).

Keep the whole report short — this is meant to move fast into an actual GitHub issue/PR, not become its own research document.

Guardrails

• Stay in scope. If you notice a UI/navigation/link/accessibility thing, don't report it — this skill is content-only.
• Never hallucinate a bug — verify or mark unconfirmed.
• Speed over coverage — 5–8 well-checked pages beats 20 shallow ones.
• Never reproduce large verbatim chunks of the docs — paraphrase and point to the location instead.