Verify With Docs

Verify With Docs (Retrieval-First)

Your training data has a cutoff and libraries move fast, so for any code that touches a specific dependency, retrieve before you write. Prefer retrieval over pre-training memory — never trust the model's memorized API surface when the current docs are reachable.

When this applies

Reach for this skill when the task:

• implements against a named library/framework/SDK, especially a fast-moving one (web frameworks, cloud SDKs, AI/LLM SDKs, build tools, ORMs);
• depends on exact signatures, option names, return shapes, or config keys;
• says "latest", "current", "did X change in version Y", or names a version;
• is failing with an error that looks like a wrong/renamed API.

Skip it for stable stdlib usage you are certain of, or pure logic with no external API surface.

References Local-First

Before fetching from the web, check if the target library is available as a local reference in opencode.jsonc → references. If mounted (e.g., via references: { "opencode": { "repository": "anomalyco/opencode" } }), read the source code from the local clone first. Only fall back to web fetch if:

• The reference is outdated (commit older than the version in use)
• The reference does not cover the relevant code paths
• No reference is mounted for the target library

The loop

1. Pin the exact version. Read the version actually in use before reading any docs — the docs must match it.
   • JS/TS: package.json + the lockfile (node_modules/<pkg>/package.json is the ground truth for the installed version).
   • Python: pyproject.toml / requirements.txt / pip show <pkg>.
   • Go: go.mod. Rust: Cargo.toml / Cargo.lock.
2. Go to the primary source, matched to that version. Prefer, in order: official docs for that version → the library's own repo (tag/branch matching the version) → typed definitions shipped with the package (.d.ts, stubs, godoc) → reputable references. Skip blog posts and Q&A for signatures.
3. Extract only what you need. The exact signature, required vs optional params, return type, error modes, and any breaking-change note between the installed version and what memory assumes. Don't dump whole pages into context — quote the minimal relevant lines.
4. Report verified facts with citations. Every signature you hand back must carry a source URL or file path so the implementing agent can trust it.
5. Only then implement — against the retrieved API, not the remembered one.

Prefer mounted references over repeated fetches

For a library you consult often, mount it once as an OpenCode reference so agents search a local, version-pinned copy instead of re-fetching docs every session (cheaper and offline-safe):

// opencode.json
"references": {
  "somelib": {
    "repository": "https://github.com/org/somelib",
    "branch": "v4"          // pin to the version you actually use
  },
  "internal-lib": {
    "path": "./vendor/internal-lib",
    "description": "Our vendored copy — read-only context"
  }
}

Then search the mounted reference for the exact API before answering. If the reference is missing or stale, refresh it rather than falling back to memory.

Output format

## Verified against docs
- <API/signature> — source: <URL or path> (version <x.y.z>)
- <option/return shape> — source: <URL or path>

## Changed / gotchas (if any)
- <what differs from a naive memory-based guess, and why it matters>

## Ready to implement
<one line: the caller can now code against the above without guessing>

Anti-patterns

• Writing the call first and "checking later" — verify before you write.
• Citing a doc version that doesn't match the installed version.
• Pasting entire doc pages into context instead of the few relevant lines.
• Trusting a blog/Q&A snippet over the official docs or the shipped type definitions.