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

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