up-to-date

name	up-to-date
description	Use when writing, editing, or refactoring code that calls any third-party SDK, API, or library; installing or importing external packages; debugging when an API call returns success but the expected side-effect doesn't happen; hitting 4xx errors from an external API; or when something 'doesn't work' and the code involves an external service.
license	MIT

Up To Date

Rule

Before writing or debugging ANY code that touches an external package or API, fetch the real documentation first. Training data is stale — the docs are the only source of truth for current API contracts, parameter shapes, and SDK method signatures.

Before proceeding, confirm none of these apply:

1. Writing or changing an API call without reading current docs
2. Guessing why an API call silently fails
3. Proposing a fix based on intuition without verifying the actual API contract

If any apply → complete the Mandatory Steps below before writing a single line of code.

When This Triggers

This skill triggers on any of the following — load it BEFORE doing anything else:

Direct triggers (writing code)

• Installing a package (npm install, pip install, brew install)
• Importing or using any third-party library
• Calling any external API (REST, GraphQL, SDK methods)
• Modifying or refactoring existing integration code
• Moving API calls between files (e.g., centralizing into a service module)

Diagnostic triggers (debugging)

• An API returns success but the expected side-effect didn't happen — this is the #1 missed trigger
• User says something "doesn't work" and external services are involved
• The service dashboard shows the request was received but the expected result is missing
• A try/catch is swallowing errors and you need to understand what the API actually expects
• Any 4xx error from an API you haven't checked docs for recently

Refactoring triggers

• Changing how an SDK is initialized (singleton, lazy, etc.)
• Changing how SDK method parameters are constructed
• Moving SDK calls to a different file or module (parameter shapes may need adjustment)

Mandatory Steps

1. Check Version

# What's installed?
cat node_modules/<pkg>/package.json | grep '"version"'
# or: pip show <pkg> | grep Version

# What's latest?
npm info <pkg> version
# or: pip index versions <pkg>

If 1+ major versions behind, read the changelog/migration guide before writing code — current docs may not match the installed version.

2. Fetch Real Docs (pick one or more)

Context7 (preferred for popular libraries):

resolve-library-id → query-docs with specific endpoint/method question

Web fetch (WebFetch in Claude Code, fetch_webpage in Copilot, or your agent's equivalent):

Fetch the official API reference page for the specific endpoint or method being used

DeepWiki (if available):

Fetch from deepwiki.com for GitHub-based packages

Do NOT skip this step. Do NOT write integration code from memory. Do NOT diagnose failures from memory.

3. Compare Code vs Docs

Check for mismatches:

• Parameters code sends vs parameters docs accept
• Value types and shapes — does the parameter expect a specific type, object structure, or callback signature?
• Endpoint paths code hits vs current paths
• Response shape code expects vs current shape
• Required vs optional fields
• Removed or renamed parameters
• How the SDK expects values to be constructed — wrapper functions, factory methods, specific class instances vs plain objects

4. After Changes

• Remove deprecated env vars and parameters
• Update all call sites
• Build to verify types
• Test live and verify the actual downstream effect — don't just check the HTTP status code. Confirm the resource appears where expected (service dashboard, database, UI). A 200 with a valid-looking response body can still mean nothing happened.

Common Failure Patterns

Pattern	What Happens	Root Cause
200 OK Trap	API returns success, but resource is orphaned/invisible	Deprecated parameter silently ignored — new replacement exists in docs
Wrong Diagnosis	Multiple fix attempts blame infrastructure	SDK expects a specific value format (wrapper, factory, class instance) that differs from the plain value

Anti-Patterns

Pattern	Risk
Writing API code from memory	Parameters may not exist anymore
Diagnosing API failures from memory	You'll guess wrong and waste turns on fake fixes
Guessing infrastructure issues before checking API contract	The problem is usually in how you call the API, not the environment
catch (e) { return { success: true } }	Hides failures completely
catch (e) { logger.error(e) } with no rethrow or user feedback	Failure is logged but invisible to debugging flow
if (CONFIG) { callAPI() } with no else-log	Silent skip when config is missing
Passing extra params API won't reject	Silently ignored, feature broken
Trusting 200 + valid response body = success	Resource may exist but be orphaned/invisible
Verifying only the API response, not the downstream system	Missed side effects go undetected
Passing a plain value when the SDK expects a wrapped/constructed type	SDKs often require specific constructors, factory methods, or wrapper objects — not raw values

Decision Flowchart

User reports bug with external service
  │
  ├─ Is there a try/catch swallowing the error?
  │   └─ YES → Temporarily log the full error BEFORE guessing
  │
  ├─ Does the API return success but side-effect is missing?
  │   └─ YES → FETCH DOCS FIRST. Do NOT guess the cause.
  │            Compare exact parameter shapes, types, and values
  │            against what the docs specify.
  │
  └─ Is the error a 4xx?
      └─ YES → FETCH DOCS. Check which parameters are valid
               for the current SDK version.

Bundled Resources

scripts/check_versions.py

Automated version checker for npm and pip packages. Run it to quickly identify outdated dependencies:

# Check a single npm package
python3 scripts/check_versions.py npm resend
# Check all package.json dependencies
python3 scripts/check_versions.py npm --all
# Check a pip package
python3 scripts/check_versions.py pip requests

references/doc-urls.md

Quick-reference table of official API documentation and changelog URLs for 30+ popular packages (email, payments, AI, databases, auth, cloud, analytics, frameworks). Consult this before searching — the correct URL may already be listed.