Research

Research Skill

Tool-assisted research with Tavily integration. Transforms basic questions into comprehensive search strategies using AI-optimized web search.

Setup

This skill includes a bundled Tavily CLI script at scripts/tavily-cli.ts.

Requirements

• Deno - Install from https://deno.land
• Tavily API Key - Get one at https://tavily.com (free tier available)

Configuration

Set your API key:

export TAVILY_API_KEY="your-key-here"

Create an alias for convenience (add to your shell profile):

# Adjust path to where this skill is installed
alias tavily='deno run --allow-net --allow-env /path/to/skills/research/scripts/tavily-cli.ts'

Or run directly:

deno run --allow-net --allow-env ./scripts/tavily-cli.ts "your query"

Commands below use tavily assuming the alias is configured.

Quick Reference

Common Commands

# Basic search
tavily "your query"

# With AI answer summary
tavily "your query" --answer

# Deep search with more results
tavily "your query" --depth advanced --results 10 --answer

# News/recent content
tavily "your query" --topic news --time week

# Exclude familiar sources to find new perspectives
tavily "your query" --exclude wikipedia.org,reddit.com

Phase Summary

| Phase | Type | Purpose |

|-------|------|---------|

| 0 | Manual | Analyze topic, set scope |

| 1 | Tavily | Discover expert terminology |

| 2 | Tavily | Foundational search |

| 3 | Tavily | Counter-perspectives |

| 4 | Manual | Synthesize findings |

Scope → Tavily Depth

| Decision Stakes | Tavily Settings |

|-----------------|-----------------|

| Low, reversible | --depth basic --results 3 |

| Moderate | --depth basic --results 5 --answer |

| High, irreversible | --depth advanced --results 10 --answer |

Phase 0: Analysis

Goal: Structure topic before searching. Prevents unfocused searches and scope mismatch.

Scope Calibration

Before searching, assess stakes:

| Decision Type | Confidence Needed | Research Depth |

|---------------|-------------------|----------------|

| Reversible, low-stakes | 60-70% | Quick scan (minutes) |

| Reversible, moderate | 75-85% | Working knowledge |

| Irreversible, moderate | 85-90% | Solid grounding |

| Irreversible, high | 90-95% | Deep expertise |

Analysis Template

# Research Analysis: [Topic]

## Core Concepts
- **Primary terms:** [Key terms requiring definition]
- **Terminology variants:** [Synonyms, jargon, historical terms]
- **Ambiguous terms:** [Terms with multiple meanings]

## Stakeholders
- **Primary actors:** [Who is directly involved?]
- **Affected groups:** [Who bears consequences?]
- **Opposing interests:** [Who benefits from different outcomes?]

## Temporal Scope
- **Historical origins:** [When did this begin?]
- **Key transitions:** [What changed and when?]
- **Current state:** [What's happening now?]

## Domains
- **Primary field:** [Main discipline]
- **Adjacent fields:** [Related disciplines]

## Controversies
- **Active debates:** [What's contested?]
- **Competing frameworks:** [Different ways of understanding]

Phase 0 Checklist

• [ ] Identified primary terms
• [ ] Listed potential stakeholders
• [ ] Assessed decision stakes
• [ ] Determined appropriate research depth

Phase 1: Vocabulary Discovery

Goal: Discover expert terminology to unlock deeper search results.

Why Vocabulary Matters

• Outsider terms → introductory material
• Expert terms → research, nuanced analysis
• Cross-domain terms → bridge bodies of work

Tavily Commands for Vocabulary Discovery

| Discovery Need | Command |

|----------------|---------|

| Expert terminology | tavily "[topic] terminology experts" --answer |

| Academic terms | tavily "[topic] academic research terminology" --answer |

| Cross-domain synonyms | tavily "[topic] also known as called" --answer |

| Historical terms | tavily "[topic] history original term" --answer |

Vocabulary Discovery Process

• Run initial terminology search:

   tavily "[topic] terminology" --answer --results 5

• From results, note:
• Expert terms (technical vocabulary)
• Outsider terms (popular/introductory language)
• Cross-domain equivalents

• Update vocabulary map (template below)

• Re-run searches with expert terms:

   tavily "[expert-term]" --answer

• Compare result quality - expert terms should surface deeper content

Vocabulary Map Template

## Core Terms
| Term | Domain | Depth Level |
|------|--------|-------------|
| [expert term] | [field] | Expert |
| [outsider term] | General | Introductory |

## Cross-Domain Synonyms
| Concept | Terms by Domain |
|---------|-----------------|
| [concept] | Field A: [term], Field B: [term] |

## Depth Indicators
| Level | Terms | What They Surface |
|-------|-------|-------------------|
| Introductory | [terms] | Overviews, explainers |
| Expert | [terms] | Research, nuanced analysis |

Phase 1 Checklist

• [ ] Ran terminology discovery search
• [ ] Identified expert vs. outsider terms
• [ ] Mapped cross-domain synonyms
• [ ] Created vocabulary map

Phase 2: Foundational Search

Goal: Build foundational understanding with authoritative sources.

Question Pattern → Tavily Command

| Question Pattern | Strategy | Command |

|------------------|----------|---------|

| "What is X?" | Consensus from authorities | tavily "[expert-term] definition" --answer --depth advanced |

| "Should I X?" | Pros/cons, alternatives | tavily "[expert-term] pros cons comparison" --answer |

| "Is X true?" | Evidence, counter-evidence | tavily "[claim] evidence research" --answer --depth advanced |

| "How do I X?" | Step-by-step, pitfalls | tavily "[expert-term] guide tutorial" --answer |

| Historical context | Origins and evolution | tavily "[topic] history origins development" --answer |

Source Type Selection

| Source Type | Best For | Tavily Approach |

|-------------|----------|-----------------|

| Academic/Research | Mechanism, causation | --depth advanced --results 10 |

| Practitioner content | How things work, edge cases | --topic general --answer |

| News/Current | Recent developments | --topic news --time week |

| Official docs | Technical specs, policy | --include [official-domain] |

Foundational Search Process

• Start with expert terminology from Phase 1

• Run foundational queries:

   # Definition/overview
   tavily "[expert-term] comprehensive overview" --answer --depth advanced

   # Key perspectives
   tavily "[expert-term] major approaches" --answer --results 7

• For each major perspective found, get 2-3 authoritative sources:

   tavily "[perspective-name] [expert-term]" --answer --results 5

• Track sources in research notes

Phase 2 Checklist

• [ ] Used expert terminology from Phase 1
• [ ] Searched for foundational overview
• [ ] Identified 2-3 major perspectives
• [ ] Found authoritative sources per perspective
• [ ] Tracked sources

Phase 3: Counter-Perspective Search

Goal: Explicitly find opposing viewpoints to avoid confirmation bias.

Why Counter-Perspectives Matter

Single-perspective research:

• All sources support one viewpoint
• Missing counterarguments
• Echo chamber risk

Tavily Commands for Counter-Perspectives

| Need | Command |

|------|---------|

| General criticism | tavily "[topic] criticism problems" --answer |

| Opposing viewpoint | tavily "[topic] skeptics critique" --answer |

| Alternative approaches | tavily "[topic] alternatives instead of" --answer |

| Failure cases | tavily "[topic] failures when wrong" --answer |

| Avoid echo chamber | tavily "[topic] debate" --exclude [familiar-sources] |

Counter-Perspective Process

• Identify your current understanding/lean

• Search for strongest counterargument:

   tavily "[topic] strongest argument against" --answer --depth advanced

• Exclude sources you've already seen:

   tavily "[topic]" --exclude [domains-already-searched]

• Search for failure modes:

   tavily "[topic] when fails problems limitations" --answer

• Document opposing perspectives in research notes

Phase 3 Checklist

• [ ] Identified current understanding/position
• [ ] Searched for strongest counterargument
• [ ] Used --exclude to find new sources
• [ ] Searched for limitations/failure cases
• [ ] Documented opposing perspectives

Phase 4: Synthesis

Goal: Synthesize findings with explicit confidence markers.

Completion Criteria

Minimum Viable (Quick Decisions)

• [ ] Can define core concepts in own words
• [ ] Know 2-3 major perspectives
• [ ] Found authoritative source per perspective
• [ ] Identified known unknowns

Working Knowledge (Most Decisions)

• [ ] Can explain historical context
• [ ] Understand stakeholder positions
• [ ] Encountered counterarguments
• [ ] Checked multiple domains

Deep Expertise (High-Stakes)

• [ ] Traced claims to primary sources
• [ ] Can evaluate competing evidence
• [ ] Understand knowledge limitations

Diminishing Returns Signals

Stop when:

• New sources cite same foundational works (circular)
• New searches return familiar content (repetitive)
• Each hour adds less than previous (marginal)
• Can make decision or take action (sufficient)

Confidence Markers

| Level | Phrases to Use |

|-------|----------------|

| Established | "X is...", "X works by..." |

| Strong evidence | "Evidence strongly suggests..." |

| Moderate evidence | "Most sources report..." |

| Limited evidence | "One study found..." |

| Unknown | "No reliable information found..." |

Synthesis Template

## Summary
[Direct answer to question]

## Confidence Level
[High/Medium/Low] - [Justification]

## Key Findings
1. [Finding with source type]

## Perspectives
| Perspective | Key Argument | Source Quality |
|-------------|--------------|----------------|
| [view] | [argument] | [assessment] |

## Counter-Evidence
- [What argues against the main conclusion]

## Caveats
- [What wasn't consulted]
- [What assumptions were made]

## For Deeper Investigation
[What would increase confidence]

Phase 4 Checklist

• [ ] Met completion criteria for stakes level
• [ ] Checked diminishing returns signals
• [ ] Applied confidence markers
• [ ] Completed synthesis template
• [ ] Stored findings for future reference

Tavily Command Reference

Basic Usage

tavily "search query" [options]

Options

| Option | Description | Values |

|--------|-------------|--------|

| --answer | Include AI-generated answer summary | flag |

| --depth | Search depth | basic (default), advanced |

| --results | Number of results | 1-20 (default: 5) |

| --topic | Topic category | general (default), news, finance |

| --time | Time filter | day, week, month, year |

| --include | Only include domains | comma-separated |

| --exclude | Exclude domains | comma-separated |

| --raw | Include raw page content | flag |

| --json | Output as JSON | flag |

Scenario → Command Mapping

| Research Scenario | Command |

|-------------------|---------|

| Quick overview | tavily "query" --answer |

| Deep dive | tavily "query" --depth advanced --results 10 --answer |

| Recent news | tavily "query" --topic news --time week |

| Academic focus | tavily "query" --depth advanced --include scholar.google.com,arxiv.org |

| Avoid Wikipedia | tavily "query" --exclude wikipedia.org |

| Fresh perspectives | tavily "query" --exclude [already-seen-domains] |

| Financial data | tavily "query" --topic finance --answer |

| Raw content for analysis | tavily "query" --raw --json |

Diagnostic States

Use these to identify where research is stuck and which phase to revisit.

| State | Symptom | Phase to Revisit |

|-------|---------|------------------|

| R0: No Analysis | Searching without structuring topic | Phase 0 |

| R1: No Vocabulary | Using outsider terms, finding only surface content | Phase 1 |

| R2: Single-Perspective | All sources support one view | Phase 3 |

| R3: Domain Blindness | Searching only in familiar field | Phase 1 (cross-domain terms) |

| R4: Recency Bias | Only recent sources | Phase 2 (historical queries) |

| R5: Breadth Without Depth | Many tabs, no synthesis | Phase 4 |

| R6: Completion Uncertainty | Unsure when to stop | Phase 4 (completion criteria) |

| R7: Complete | Can explain, identify uncertainties, act | Done |

Quick Diagnostic

• Can you explain the topic in expert terminology? → If no, Phase 1
• Have you found opposing viewpoints? → If no, Phase 3
• Can you state your confidence level with justification? → If no, Phase 4
• Is your research depth proportional to stakes? → If no, Phase 0

Anti-Patterns

| Pattern | Symptom | Fix |

|---------|---------|-----|

| Confirmation Trap | Searching to confirm, not learn | Phase 3: Search for strongest counterargument |

| Authority Fallacy | Accepting claims by source prestige | Evaluate evidence, not source |

| Recency Trap | Only recent sources | Phase 2: Historical context queries |

| Breadth Trap | 50 tabs, none read | Phase 4: 3-source rule, synthesize before continuing |

| Single-Source | One source as final answer | Require 3 independent sources |

| Jargon Blind Spot | Missing other fields' terminology | Phase 1: Cross-domain vocabulary |

| Infinite Rabbit Hole | Lost original purpose | Phase 0: Return to scope/stakes |

| Echo Chamber | Same sources repeatedly | Phase 3: Use --exclude flag |

Output Persistence

Output Discovery

Before doing any other work:

• Check for context/output-config.md in the project
• If found, look for this skill's entry
• If not found or no entry for this skill, ask the user first:
• "Where should I save output from this research session?"
• Suggest: explorations/research/ or a sensible location for this project
• Store the user's preference

What to Store

| Layer | Contents |

|-------|----------|

| Vocabulary Map | Terms, domains, depth levels |

| Sources | URLs, relevance scores, quality notes |

| Synthesis | Summary, confidence, findings, caveats |

| Query Log | Tavily commands that worked/failed |

| Gaps | What remains unknown |

File Naming

Pattern: {topic}-research-{date}.md

Example: competency-frameworks-research-2025-01-15.md

Integration Points

| Skill | Connection |

|-------|------------|

| doppelganger | Research informs decisions; apply /truth-check to findings |

| context-networks | Store research findings in appropriate network node |

| boundary-critique | Apply to advice and recommendations encountered |

Health Check Questions

During research, ask:

• Am I searching to learn or to confirm?
• What's the strongest argument against my current view?
• Have I looked outside my familiar domains?
• Am I using expert or outsider vocabulary?
• Is my depth proportional to the stakes?
• Have I stored what I've learned for future use?

Source Framework

Derived from: references/research-framework.md