# Pydantic AI Docs Drift Documentation lives in `docs/` (published by `pydantic/unified-docs`, with `docs/navigation.yml` defining its routes and sidebar), 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/`, `docs/navigation.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 `docs/navigation.yml`. 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 Open issues were prefetched before the sandbox started. Before filing, first check this sweep's own prior findings with a local label filter: ```bash jq '.[] | select(any(.labels[]; .name == "docs-drift")) | {number, title, url}' \ /tmp/gh-aw/agent/github-context/open-issues.json ``` Only if that is inconclusive, widen to a full open-issue scan and grep locally for keywords from your finding: ```bash jq '.[] | {number, title, labels: [.labels[].name], url}' \ /tmp/gh-aw/agent/github-context/open-issues.json ``` Do not enumerate issues with `gh` from inside the sandbox; list requests can stall until the workflow times out. 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]