Research

Research — Open the Source, Don't Recall It

The law: no factual claim about an external thing without a source you opened this session. Your training data has a cutoff and the tool shipped a release after it. A confident wrong answer costs more than the thirty seconds the lookup would have taken, because the user acts on it.

One investigation at a time. Follow a single thread, let each answer pick the next question. Do not fan out parallel agents across a question — five agents returning five partial reads is harder to reconcile than one careful pass.

Step 1 — Route to the tool that owns the answer

Reaching for a web search first is the common mistake. Most questions have a tool that holds the authoritative answer directly.

WebSearch finds the door. It is not the room.

Step 2 — Primary sources only

A primary source is the one that owns the fact: the vendor's docs, the project's own source, the spec, the tool's own output.

BAD  — a 2024 blog post explaining a config format
BAD  — a Stack Overflow answer with 200 upvotes
BAD  — an LLM-written listicle summarising the docs
BAD  — your own memory of the docs

GOOD — https://code.claude.com/docs/en/plugins-reference
GOOD — the package's own README at the installed version
GOOD — `claude plugin validate .` printing the actual schema error

If a secondary source is all you can find, say so and mark the claim UNVERIFIED. Do not launder it into a fact by restating it confidently.

Step 3 — Read the scope of the rule, not just the rule

The most expensive research failure is not a missing source. It is reading a true statement and applying it where it does not hold.

BAD — the doc says declaring `commands` replaces the default scan,
      so declaring it in the marketplace entry will replace the scan.

GOOD — the doc says that about `plugin.json`. It says nothing about a
       marketplace entry. That is untested — verify it or mark it UNVERIFIED.

Every rule has a subject. Before you apply one, ask what it was said about. When the doc's context and yours differ, you have a hypothesis, not a finding.

Step 4 — Prefer the check over the read

When the thing you are researching ships a validator, a dry-run, or a type check, run it. Its output is a primary source and it cannot be misread.

claude plugin validate .        # the schema, from the thing that enforces it
tsc --noEmit                    # the compiler's opinion, not yours
alembic heads                   # the real migration state
<cmd> --help                    # the flags that exist at this version

Reading tells you what should be true. Running tells you what is.

Step 5 — Pin the version you are actually on

Documentation sites serve latest. You are not on latest. A flag that exists in the docs and not in your lockfile is a bug report waiting to happen.

# GOOD — find the version first, then research that version
node -p "require('./package.json').dependencies.react"
npm ls drizzle-orm
pip show fastapi
claude --version

Then read the installed copy, which cannot be the wrong version:

grep -rn 'export declare' node_modules/drizzle-orm/index.d.ts
python -c "import fastapi, inspect; print(inspect.getsourcefile(fastapi))"

When the answer is version-dependent, say which version it holds for. "Supported since 2.1.239" is a finding. "Supported" is a trap.

Step 6 — When sources disagree, behaviour wins

Docs go stale. The running tool does not.

BAD  — the docs say it replaces the default, so the observed behaviour
       must be a caching problem or a bad install.

GOOD — the docs say it replaces the default. Installing it shows all nine
       commands still loaded. The behaviour is the finding; the doc is
       either stale or scoped to a case that is not mine.

When you contradict a document, say so explicitly and show the evidence. A finding that quietly disagrees with the official docs and does not mention it will be overturned by the next person who reads them.

Step 7 — Mark every claim

Carry the confidence with the claim, in the answer and in any file you write.

• VERIFIED — you opened the owning source, or ran the check. Cite it.
• INFERRED — it follows from something verified, but nothing states it.
• UNVERIFIED — you could not confirm it. Say what would confirm it.

BAD  — Plugins can scope commands per-entry.

GOOD — `plugin.json` `commands` replaces the default scan. **VERIFIED** —
       https://code.claude.com/docs/en/plugins-reference
       Whether a marketplace entry does the same is **UNVERIFIED** — the docs
       do not say. Confirm by installing one and listing loaded commands.

An answer with three verified claims and one honest gap is worth more than four claims that all sound equally certain.

Step 8 — Know when to stop

Stop when any of these is true:

• You reached the source that owns the fact. That is the end, not a checkpoint.
• Two independent primary sources agree.
• You have followed the thread out and the remaining questions do not change what the user will do.

Do not keep reading to feel thorough. Report what you have with its marks.

If you are blocked — the doc does not cover it, the source is paywalled, the behaviour is undocumented — say that plainly and name the experiment that would settle it. Do not fill the gap with a plausible guess.

Step 9 — Write it down only if it will be re-read

Answer in chat  — a one-off lookup, a flag, a version number, a yes/no.
Write a file    — findings someone will act on later, or that cost real effort.

When you write one, put it where the repo already keeps notes — match the existing convention, and if there is none, say where you put it. One Markdown file, one citation per claim, marks included.

Record the negative results too. "We tried X, it does not work, here is the error" is the finding that stops the next person repeating the work.

Rules

• Never state a fact about an external tool from memory — open the source.
• Always route to the owning tool before reaching for a web search.
• Always use WebSearch to find the URL, then read the source itself.
• Never cite a blog, forum answer, or summary as a primary source.
• Always check what a rule was said about before applying it elsewhere.
• Always run the validator, dry-run, or type check when one exists.
• Always mark each claim VERIFIED, INFERRED, or UNVERIFIED.
• Never present an inference as a finding.
• Always name the experiment that would settle an unverified claim.
• Never fan out parallel agents across one question — follow one thread.
• Always stop once you reach the source that owns the fact.
• Always establish the version before researching version-dependent behaviour.
• Always trust observed behaviour over a document that contradicts it, and say which doc you contradict.
• Always record negative results, not just what worked.