official-docs-first

Official docs FIRST (R2 enforcement)

Trigger

• ANY external technology in scope: SDK, API, library, framework, package, database driver, AI provider, MCP server
• Knowledge cutoff is months old. Frameworks ship breaking changes weekly.
• "I think I know this library" is exactly when you're wrong (knowledge drift on familiar things is highest)

Mandatory steps BEFORE writing code

1. Identify external technologies in scope

• List explicitly: "This task touches: Pydantic AI 0.0.x, FastAPI, SQLModel, Alembic, OpenAI SDK"
• Don't assume "minor versions don't matter" — they do for active projects

2. For each: query Context7 MCP

mcp__context7__resolve-library-id   →  get the /org/library ID
mcp__context7__get-library-docs     →  fetch current docs

3. If Context7 has nothing → WebFetch official URL

• Find the canonical documentation page (NOT a tutorial blog post)
• WebFetch it
• Quote the specific clause that affects your code + URL

4. Compare with HANDOFF/SPEC hypothesis

• If existing notes say "API takes parameter X" — verify in fetched docs
• Flag any contradiction explicitly

5. Cite in your work

Format in your reasoning:

Per [docs URL]: "exact quoted clause about the API" Therefore the call shape is: client.method(arg=X, optional=Y)

6. ONLY THEN start writing code

• Code must reference what you read
• If docs are ambiguous → escalate to owner WITH proposed default (R4), not as open question

Verified provider docs to know

Provider	Canonical docs URL
Anthropic	https://docs.anthropic.com
Claude Code	https://code.claude.com/docs/en
OpenAI	https://platform.openai.com/docs
Pydantic AI	https://ai.pydantic.dev
FastAPI	https://fastapi.tiangolo.com
SQLModel	https://sqlmodel.tiangolo.com
Alembic	https://alembic.sqlalchemy.org
xAI	https://docs.x.ai

Anti-patterns

• ✗ "I'll just write it from memory, this library hasn't changed much"
• ✗ Reading a 2-year-old blog post instead of current official docs
• ✗ Trusting auto-generated docs from a fork without checking canonical
• ✗ Citing docs without quoting the specific clause