Read Source Code at Runtime, Not Cache It

The Problem

AI agents constantly face outdated knowledge. Training data has a cutoff, documentation lags behind releases, and cached reference files go stale the moment a package updates.

The typical workaround — saving documentation or API specs locally — creates a maintenance burden: you have to remember to update your cached copy every time the upstream changes. You won’t remember. The cache will drift.

The Pattern: Read Source Code Live

Instead of caching documentation, read the actual source code at runtime when you need authoritative answers.

I use this pattern in two ways across my Claude Code plugin ecosystem:

1. WebFetch Official Docs (ai-docs-guide / claude-config-guide plugins)

My ai-docs-guide plugin forces Claude to fetch the latest documentation every time:

# The key instruction in the skill:
"You MUST WebFetch official documentation - never answer from memory!"

No local cache. Every question triggers a live fetch from the official docs URL. When OpenAI updates their API, my plugin automatically gives the right answer — zero maintenance.

2. Read Package Source Code Directly

This is the case that made the pattern click.

I was building an interactive map drill-down feature for a Shiny dashboard — click on the US in a world map, it zooms into US states. Simple concept, right?

The problem: plotly click events weren’t working inside a Shiny module. The documentation doesn’t explain how event_data() interacts with module namespacing. Stack Overflow answers contradicted each other. Claude gave plausible-but-wrong solutions.

After several failed attempts, I tried something different: just read the source code.

# Read the R function implementation
Rscript -e "body(plotly::event_data)"

# Read the JavaScript event handler
cat .../plotly/htmlwidgets/plotly.js | grep -A 50 "eventDataWithKey"

In ~100 lines of source code, I found three undocumented behaviors:

1. Source IDs bypass module namespace — plotly.js writes to Shiny.setInputValue(event + "-" + source, ...) which goes to the root session, not the module session. Fix: source = session$ns("worldmap")

2. Choropleth click events don’t include $location — The JS eventDataWithKey() function only extracts curveNumber, pointNumber, x, y, z, customdata, key. Not location. You have to pass country codes through customdata.

3. Default priority deduplicates clicks — priority = "input" means clicking the same country twice won’t trigger the observer the second time. Fix: priority = "event"

Three bugs. Zero documentation. Solved in 2 minutes by reading source code.

Without reading the source, I would have been debugging blind — trying random combinations of parameters, searching for answers that don’t exist on the internet. With the source code, I could see exactly how the system works and fix it surgically.

Why Not Cache the Findings?

After discovering these behaviors, my first instinct was to save them in a reference file. I resisted, because:

1. plotly updates — A future version might add location to the event data. My cached reference would say it doesn’t exist, leading to unnecessary workarounds.

2. The read is fast — Rscript -e "body(plotly::event_data)" takes 200ms. No performance reason to cache.

3. The source is the truth — Documentation describes intent. Source code describes reality. When they disagree, source wins.

What I did save was the knowledge that “you should read the source” — not the specific findings. The pattern, not the cache.

The Principle

Cache what you control. Read live what others control.

Cache locally	Read live
Your own architecture rules	Package source code
Project conventions	API documentation
Domain knowledge	Function signatures
Things that change when YOU decide	Things that change when THEY release

Implementation

In Claude Code plugins, the pattern maps to skill tool permissions:

# Skill frontmatter
allowed-tools: WebFetch, Read, Glob, Grep, Bash

• WebFetch: Official documentation URLs
• Read + Glob + Grep: Local package source files
• Bash: Rscript -e "..." for R introspection

And the critical instruction:

"You MUST read the source — never answer from memory!"

This single line prevents the most common AI failure mode: confidently wrong answers based on stale training data.

Impact

For the plotly case:

Approach	Estimated iterations	Confidence
Stack Overflow + guessing	10+ attempts	Low
Ask AI from memory	5+ attempts (plausible but wrong)	Medium (false)
Read source code	1 read, 3 fixes	High (understood mechanism)

The pattern isn’t just faster — it produces understanding. After reading the source, I know why it works. When plotly updates, I know where to look again.

Takeaway

Next time an AI agent gives you a confident answer about how a library works — and it doesn’t work — don’t iterate on the guess. Read the source. It’s always right, it’s always current, and it’s always available.