Research

Verified Research

Quick Start

1. Fetch actual source content (don't trust snippets) 2. Verify claims before presenting 3. Report failures explicitly

Tool Priority

1. GitHub repos → gh api via Bash 2. npm packages → npmx.dev API via WebFetch (see npm-package-research.md) 3. Doc pages → tavily_extract_process 4. Quick answers → ai_search (perplexity/kagi_fastgpt/exa_answer) 5. Discovery → web_search or github_search 6. Fallback → Clone repo via subagent

Core Rules

• Never present unverified findings - fetch actual content first
• Partial data ≠ success - try next tool, report failures
• No source substitution without user consent
• Flag contradictions - don't silently pick one source

References

• verification-patterns.md - Source conflicts, cutoff handling
• ai-search-providers.md - exa_answer, perplexity, kagi usage
• hallucination-prevention.md - CoVe, atomic facts
• repo-cloning-pattern.md - Subagent clone workflow
• partial-data-failures.md - Rate limits, fallbacks
• npm-package-research.md - npmx.dev type docs, version resolution, fallbacks

AI Search Providers

Provider Selection

exa_answer Guidance

When to use: Questions needing semantic/conceptual understanding, not keyword matching.

Strengths

• Neural search finds conceptually related content
• Returns citations you can verify
• Good for exploratory "how/why" questions

Limitations

• Synthesized answer = potential for synthesis errors
• Must still verify critical claims against cited sources
• Not a substitute for fetching primary docs

Workflow Pattern

1. Use exa_answer for initial conceptual understanding
2. Extract citations from response
3. Fetch cited URLs with tavily_extract to verify key claims
4. Cross-check against primary sources if available
5. Only present verified information to user

Anti-Patterns

❌ Use exa_answer → present synthesized answer as verified fact
❌ Treat exa_answer as standalone tool (it's part of verification workflow)

gh CLI for GitHub Repos

# Get source files directly
gh api repos/OWNER/REPO/contents/PATH --jq '.content' | base64 -d

# Get repo metadata + version
gh repo view OWNER/REPO --json description,latestRelease

Hallucination Cascade Prevention

Unverified claims in step 1 corrupt all downstream reasoning.

The Cascade

1. Unverified assumption enters reasoning 2. Subsequent logic builds on assumption 3. Each step compounds the error 4. Final output appears coherent but is wrong

Chain-of-Verification (CoVe)

1. Draft initial response 2. Generate verification questions for key claims 3. Answer questions independently (fetch sources) 4. Revise draft based on verified answers

Atomic Fact Decomposition

Break complex claims into atomic facts, verify each:

Claim: "Library X v2.3 uses semver and supports Node 18+"

Atomic facts:
- Library X exists ✓
- v2.3 is a real version → fetch releases
- Uses semver → fetch versioning docs
- Supports Node 18+ → fetch compatibility docs

Self-Consistency Check

If multiple sources contradict → flag explicitly, don't pick one silently.

Anti-Patterns

• Letting search snippets become "facts" without fetch
• Reasoning from unverified assumptions
• Proceeding when source unavailable (pause instead)

Example: Cascade Failure

Step 1: "Search says library X uses semver" (snippet, not verified)
Step 2: "So patch updates are safe"
Step 3: "Updating X from 2.3.1 to 2.3.5..."
Reality: Library X doesn't use semver. Breaking changes in 2.3.3.

Correct Pattern

Step 1: Fetch library X docs/changelog
Step 2: Verify versioning policy from actual content
Step 3: Only then reason about update safety

npm Package Research

When to Use

• Researching npm package APIs, types, or interfaces
• Checking function signatures or exported types
• Understanding package surface area

Primary: npmx.dev Type Docs

Note: npmx.dev API is undocumented/unofficial. Works reliably but

has no stability guarantees.

Fetching Type Docs

WebFetch https://npmx.dev/api/registry/docs/{package}/v/{version}

• Use latest as version unless user specifies one
• Scoped packages work: @sveltejs/kit, @anthropic-ai/sdk

Response fields:

• status: "ok" → html contains rendered type documentation
• status: "missing" → package lacks .d.ts files (may use JSDoc), use fallback
• toc → table of contents for navigation
• html → interfaces, type aliases, function signatures with descriptions

Parsing the Response

• Extract relevant type information from html — don't dump raw HTML
• Use toc to identify what's available before diving into details
• Present structured findings: interfaces, their properties, and types

Fallback Chain

When npmx.dev returns status: "missing":

1. unpkg .d.ts → WebFetch https://unpkg.com/{pkg}@{ver}/dist/index.d.ts 2. GitHub repo types → gh api to fetch .d.ts from source repo 3. Package README → WebFetch https://registry.npmjs.org/{package} (has readme field) 4. Clone repo → subagent pattern for full source inspection

Anti-Patterns

• Don't assume status: "missing" means no types — package may use JSDoc (e.g. @sveltejs/kit)
• Don't dump raw HTML to user — extract relevant type information
• Don't skip checking status field — always branch on ok/missing

Example Workflow

User: "What are the exported types from svead?"

1. WebFetch https://npmx.dev/api/registry/docs/svead/v/latest
2. status: "ok" → parse html for interfaces/types
3. Found: SeoConfig (11 props), SchemaOrgProps (1 prop), Head, SchemaOrg type aliases
4. Present structured type info with source citation

User: "What does @sveltejs/kit export?"

1. WebFetch https://npmx.dev/api/registry/docs/@sveltejs/kit/v/latest
2. status: "missing" → fallback
3. Try unpkg for .d.ts files
4. Try gh api for repo source
5. Report what was found, cite sources

Partial Data Failure Pattern

The Problem

WebFetch and other tools sometimes return _something_ but not _everything_:

• Landing page summary but subpage 404s
• Truncated content
• AI-generated summary instead of raw content

Brain says: "I got something, close enough" Reality: User asked for X, you don't have X

Why This Matters

• No time pressure exists for AI - "speed" is a false excuse
• Substituting sources without consent = unilateral decision-making
• User's explicit instruction overrides AI judgement of "good enough"

Tool Effectiveness (tested)

Correct Response Pattern

1. Try primary tool (gh api or tavily_extract)
2. If partial → try next tool in priority list
3. If all partial → STOP and report:

   "Fetched [URL]. Got [partial/summary] only.
   Tried: tavily_extract (partial), WebFetch (summary).
   Options:
   - Clone repo for full source
   - Try different URLs
   - Proceed with partial data (your call)"

4. Wait for user decision

Anti-Patterns

❌ WebFetch partial → find GitHub data → proceed → hope it's fine ❌ Get summary → assume semver patches are safe → update anyway ❌ Decide "good enough" without informing user

✅ WebFetch partial → try tavily_extract → still partial → STOP → report → ask

Rate Limit Awareness

External tools have rate limits. Recognize these failure modes:

Rate-Limited Tool Handling

1. Detect rate limit (429, timeout, truncation)
2. If retryable:
   - Wait 2^n seconds (n = attempt number)
   - Max 3 retries per tool
3. If quota exhausted:
   - Switch to fallback tool if available
   - Report: "Tool X rate limited. Tried fallback Y."
4. If all tools limited:
   - STOP and report all attempts
   - Do NOT guess or hallucinate content

Tool Rate Limit Reference

Anti-Patterns

❌ Hit rate limit → immediately try same tool → fail → proceed without data ❌ Get 429 → switch tools without backoff → cascade rate limits ❌ Quota exhausted → assume partial data is complete → hallucinate rest

✅ Hit rate limit → backoff → retry → if still failing → report → ask user

Repo Cloning Pattern

For library/framework research, clone source repos to get authoritative, current information.

When to Use

• Questions about library internals/implementation
• Undocumented behavior
• Checking actual source vs docs
• Framework patterns not covered in official docs

Pattern: Subagent Clone Research

Always delegate to subagent to avoid context pollution.

Task(subagent_type=Explore) →
  1. git clone --depth 1 <repo> /tmp/research-<name>
  2. Glob/Grep for relevant patterns
  3. Read key files
  4. Return distilled findings
  5. rm -rf /tmp/research-<name>

Example Prompt for Subagent

Clone https://github.com/sveltejs/svelte to /tmp/research-svelte
Find how $effect() cleanup works internally.
Search for cleanup patterns in src/
Read relevant implementation files
Summarize findings
Delete clone when done

Key Points

• Use --depth 1 for speed (no history needed)
• Clone to /tmp/ for auto-cleanup on reboot
• Always cleanup after: rm -rf /tmp/research-*
• Subagent keeps main context clean
• Return only essential findings, not full file contents

Anti-Patterns

• Cloning in main context (trashes context)
• Full clone with history (slow, unnecessary)
• Leaving clones around (disk clutter)
• Dumping entire files back to main context

Verification Patterns

Detailed patterns for verifying sources during research.

Pattern 1: URL Research

When given a URL to research:

1. Use WebFetch to get the actual content 2. Read the complete relevant sections 3. Don't rely on summaries or snippets 4. Quote specific passages that support claims 5. Cite exact URLs

Example:

User: "Research this article about MCP performance"

WRONG approach:
- Search for article
- Present snippet results
- Make claims based on title

RIGHT approach:
- WebFetch the URL
- Read full content
- Search for performance mentions
- Quote specific data/claims
- If no performance data exists, say so

Pattern 2: Official Sources

When asked to "use official sources":

1. Search for official documentation 2. Fetch the actual pages (don't trust search snippets) 3. Read relevant sections completely 4. Quote specific parts 5. Cite exact URLs for each claim

Pattern 3: Questionable Claims

When something seems questionable:

• Fetch the original source
• Compare snippet/summary to actual content
• Call out discrepancies explicitly
• Say "I couldn't verify this" if sources don't support

Anti-Patterns

Never do these:

• Presenting search snippets as facts without verification
• Trusting summaries without checking original sources
• Citing sources you haven't actually read
• Assuming snippets accurately represent full content
• Making confident claims based on titles alone

When To Admit Uncertainty

If you can't verify because:

• Source is behind paywall/404
• Content doesn't support the claim
• Multiple sources contradict

Say so explicitly. Better to admit uncertainty than present unverified info.

Detailed Examples

Example 1: Security Documentation

User: "Research how Claude Code handles bash security"

Process:

1. Search for official Claude Code security docs 2. Fetch the actual documentation pages 3. Read security sections completely 4. Extract specific quotes about bash handling 5. Present findings with exact citations and line references

Not: Just present search result snippets

Example 2: Technical Article

User: "Study this article and tell me what it says about overhead"

Process:

1. Fetch the actual article content 2. Search for mentions of "overhead", "performance" 3. Read those sections in full context 4. Quote specific passages 5. If article doesn't mention overhead, say "The article doesn't actually discuss overhead"

Not: Assume what it says based on title/snippet

Example 3: Contradictory Sources

User: "Research whether MCP tools are faster than CLI"

Process:

1. Search for relevant sources 2. Fetch multiple actual sources 3. Compare what they actually say 4. If they contradict, present both views with quotes 5. Explain the contradiction explicitly 6. Don't pick one without evidence

Not: Present the first search result as truth

Pattern 4: Source Conflict Resolution

When sources contradict each other, use Chain-of-Verification with credibility-aware aggregation.

Detection

1. Identify the specific claim in conflict 2. Note each source's position explicitly 3. Check publication dates for each source 4. Assess source authority (official docs > blogs > forums)

Credibility Scoring

Rate sources on 1-5 scale before aggregating:

Chain-of-Verification Process

Decompose conflicting claims and verify systematically:

1. Decompose: Break claim into verifiable sub-claims 2. Query: Search each sub-claim against multiple sources 3. Annotate stance: Mark each source as support/refute/neutral 4. Score credibility: Apply 1-5 rating per source 5. Compare: Identify where sources agree/disagree 6. Aggregate: Weight by credibility, resolve via rationales

Resolution Strategies

Source Background Augmentation (SBA): Append credibility context when reasoning about conflicts. Include source type, date, and credibility score in analysis.

Ensemble approach for complex conflicts:

1. Generate answer per source 2. Compare rationales 3. Reconcile based on credibility weighting

Resolution Hierarchy

1. Prefer authoritative sources: Official documentation > peer-reviewed > news > blogs 2. Check recency: Newer sources often supersede older ones (especially in tech) 3. Seek consensus: If 3+ independent sources agree, weight that heavily 4. Verify primary sources: Trace claims back to originals when possible 5. Check topical consistency: Verify claim aligns with evidence topic

When Resolution Fails

<good-example> Source A (official docs, 2024, credibility: 5) states the API uses REST endpoints. However, Source B (developer blog, 2025, credibility: 3) claims GraphQL support was added. The higher-credibility source may be outdated. Recommend checking the changelog or testing directly. Both views presented pending verification. </good-example>

<bad-example> The API supports both REST and GraphQL. (Silently merging conflicting info without attribution or credibility analysis) </bad-example>

Present both views with citations and credibility context. Don't silently pick one.

Prioritization Table

Pattern 5: Knowledge Cutoff Handling

When research involves potentially outdated knowledge. LLMs have temporal blind spots where parametric knowledge may be outdated even within reported cutoff dates.

Claim Classification

Classify claims before researching:

Recognition Triggers

Recognize when knowledge cutoff may affect accuracy:

• Version numbers or release dates
• Current events or recent announcements
• "Latest" or "new" feature discussions
• Pricing, availability, or service status
• API endpoints or configuration options
• Words like "currently", "now", "recent", "latest"

Strategy

1. Classify the claim: Static vs time-sensitive 2. For time-sensitive: RAG required - don't rely on training data 3. Fetch actual sources - snippets may be outdated too 4. Include temporal metadata: publication date, last verified, validity window 5. Cross-reference fresh sources for any temporal claims 6. Flag outdated parametric knowledge explicitly when detected

Example

<bad-example> User: "What's the latest Claude model?"

The latest Claude model is Claude 3 Opus. (Answering from training data without verification - temporal claim treated as static) </bad-example>

<good-example> User: "What's the latest Claude model?"

Classification: Time-sensitive (version info changes) Action: RAG retrieval required

1. Search: "Anthropic Claude model 2026" 2. Fetch: anthropic.com/claude page 3. Quote: "Claude Opus 4.5 released January 2026" 4. Metadata: Source dated Feb 2026, official documentation 5. Cite: "As of Feb 2026, the latest is Claude Opus 4.5. Verify at anthropic.com/claude for current info." </good-example>

Temporal Metadata Template

Include with time-sensitive claims:

Claim: [the claim]
Type: Time-sensitive
Source: [URL]
Source date: [publication/last-updated date]
Verified: [date you fetched it]
Validity: [if known, when this fact may change]

Disclosure Template

When research may be affected by knowledge cutoff:

"This information is from [source] dated [date]. Given the
rapidly evolving nature of [topic], verify current status at
[official source URL]."

Critical Domains

Extra caution required for:

• Software versions: APIs change frequently
• Security advisories: Patches and vulnerabilities evolve
• Pricing/availability: Services change constantly
• Legal/regulatory: Laws and compliance requirements update
• Medical/scientific: New research supersedes old

Temporal Misalignment Warning

Training data may have inconsistent temporal coverage:

• Different sources in training have different effective dates
• Deduplication can cause version mixing
• Always verify time-sensitive facts via RAG even if confident