| name | current-docs-guard |
| description | Use this before implementing against any version-sensitive or unverified API: package upgrades, SDK and framework APIs (Next.js, Supabase, Vercel, Three.js, MCP, auth, browser APIs), or any external API you would otherwise write from memory unverified this session. |
current-docs-guard
Verify current official documentation before changing version-sensitive APIs. Prevents the #1 AI failure mode: confidently writing code from outdated training data.
Purpose
Before any implementation that touches version-sensitive tools (Supabase, Next.js, Vercel, Three.js, MCP, auth systems), check the current official docs. Not blogs, not courses, not memory — the actual docs at the actual URL.
Process
0. Read relevant rule references first
Before long investigations, read rules/context-hygiene.md to keep the docs check scoped and avoid context bloat. Before version-sensitive work, read the relevant rules/*.md file for the domain, if one exists.
1. Identify what's version-sensitive
Before writing any code, list: which external APIs, SDKs, or tools does this change touch?
2. Check the repo's current versions
cat package.json | grep "[library-name]"
cat pnpm-lock.yaml | grep "[library-name]" | head -5
3. Read the actual docs
Go to the official documentation URL. Not a blog post, not a Stack Overflow answer, not your training data. The docs.
Common doc URLs:
4. Compare docs against current code
Look for:
- Deprecated methods the codebase still uses
- New patterns that replace what's currently implemented
- Breaking changes between installed version and latest
- Auth patterns that have changed (very common with Supabase)
5. Document what you found
## Docs check — [library/API]
**Installed version:** [x.y.z]
**Current docs version:** [a.b.c]
**Breaking changes:** [yes/no — list if yes]
**Deprecated patterns found:** [list]
**Recommended approach:** [what the current docs say to do]
**Migration needed:** [yes/no — scope if yes]
**Confidence:** [HIGH — docs verified / MEDIUM — docs partially checked / LOW — unable to verify]
6. Flag uncertainty explicitly
If you can't verify something from docs, say so. "I believe this API works this way based on training data, but I could not verify it from current docs" is vastly better than silently guessing.
Output format
# Docs guard report — [what was checked]
## Components checked
- [Library]: v[installed] → docs say v[current]
- [API]: [method checked] — [current/deprecated/changed]
## Stale assumptions avoided
- [Pattern that would have been wrong without checking]
## Recommendation
[What to implement based on current docs]
## Risks
- [Migration risk if upgrading]
- [Compatibility concern]
## Confidence: [HIGH/MEDIUM/LOW]
Hard rules
- Never rely on training data for version-sensitive API behavior — always verify
- Never silently upgrade packages without checking migration guides
- Never use deprecated patterns when docs show the current replacement
- Never bury uncertainty — flag it explicitly with confidence level
- Prefer official docs over courses, blogs, summaries, or Stack Overflow
Connects to
issue-to-pr — invoked during implementation for version-sensitive worksupabase-guardian — complementary: docs-guard checks the API, supabase-guardian checks the schema/RLSdecision-log-adr — log decisions to upgrade or stay on current version
Common failure modes
Confidently wrong — AI generates Supabase auth code from 6 months ago. The API changed. Code compiles but auth silently breaks in edge cases. Always verify.
Checking blogs instead of docs — A Medium post from 2024 is not current documentation. Go to the official URL.
Skipping the version check — Docs for v3 look different from v2. If you're on v2, read v2 docs, not latest.
"I'm pretty sure this is right" — If you're "pretty sure" about an API method without checking, flag it as MEDIUM confidence. Let the human decide whether to verify.
