pydantic--pydantic-ai/.github/workflows/shared/prompts/pydantic-ai-docs-drift.md

Pydantic AI Docs Drift

Documentation lives in docs/ (built with mkdocs, configured in mkdocs.yml), plus README.md, CONTRIBUTING.md, and per-package AGENTS.md files. Doc code examples are tested by tests/test_examples.py.

Objective

Detect negative documentation drift — code changes that made existing documentation wrong.

Noop is the expected outcome most days. Only file an issue when existing documentation is concretely incorrect or a removed/renamed public interface is still referenced in docs.

Do NOT file issues for:

• New features that haven't been documented yet (that's the PR author's job).
• Opportunities to advertise existing features in additional docs pages.
• Minor wording that could be improved but isn't factually wrong.

Data Gathering

1. Run git log --since="7 days ago" --oneline --stat for a summary of recent commits. If there are no commits in the window, call mcp__safeoutputs__noop and stop.
2. Inventory documentation: scan docs/, mkdocs.yml, README.md, CONTRIBUTING.md, and AGENTS.md files. Do not assume a fixed structure.

What to Look For

For each commit (or group of related commits), determine whether the change made existing documentation factually wrong:

1. Public API changes — renamed/removed classes, methods, function signatures, Agent options, model/provider classes, CLI flags that are still documented under their old name.
2. Behavioral changes — altered defaults, changed exceptions/messages, modified control flow where docs describe the old behavior.
3. Dependency/tooling changes — removed dependency groups, changed build/test commands that docs reference.
4. Structural changes — moved/renamed/deleted files still referenced in docs or in mkdocs.yml nav.
5. Doc code examples — code blocks in docs/ that no longer compile or produce the documented output due to API changes.

How to Analyze

For each potentially impactful change: read the full diff, read the current docs, check whether docs were already updated in the same or a later commit in the window, and check whether an open issue/PR already tracks it.

Deduplication — mandatory before filing

Before filing, first check this sweep's own prior findings with a tight, server-side label filter — the /search/issues endpoint is blocked by the firewall proxy and there are no mcp__github__* tools, but the ?labels= filter on the issue-list endpoint is allowed:

gh api 'repos/pydantic/pydantic-ai/issues?state=open&labels=docs-drift&per_page=100' \
  --jq '.[] | select(.pull_request == null) | {number, title}'

Only if that is inconclusive, widen to a full open-issue scan and grep locally for keywords from your finding:

gh api --paginate 'repos/pydantic/pydantic-ai/issues?state=open&per_page=100' \
  --jq '.[] | select(.pull_request == null) | {number, title, labels: [.labels[].name]}'

If a matching issue exists, call mcp__safeoutputs__noop. Do NOT file duplicates.

What to Skip

• Purely internal refactors with no user-facing impact.
• Changes where docs were already updated in the same/later commit.
• Changes already tracked by an open issue or PR.
• Test-only changes.
• Minor changes where existing docs are still substantially correct.
• New features without documentation — these are NOT drift. The PR author or a separate docs PR will add them. Only flag if existing docs now contain incorrect information as a result of the new feature.

Issue Format

Title: Brief summary (e.g., "Update agent.md for new Agent output option")

Body:

Recent code changes have introduced documentation drift. The following changes need corresponding documentation updates.

Changes Requiring Documentation Updates

1. [Brief description]

Commit(s): [SHA(s)] What changed: [Concise description] Documentation impact: [Which doc file(s) and what specifically]

Suggested Actions

• [Specific, actionable checkbox per doc update needed]