Research Skill

Setup

scripts/tavily-cli.ts

Requirements

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

Configuration

export TAVILY_API_KEY="your-key-here"

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

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

tavily

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

Scope → Tavily Depth

--depth basic --results 3

--depth basic --results 5 --answer

--depth advanced --results 10 --answer

Phase 0: Analysis

Scope Calibration

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

Why Vocabulary Matters

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

Tavily Commands for Vocabulary Discovery

tavily "[topic] terminology experts" --answer

tavily "[topic] academic research terminology" --answer

tavily "[topic] also known as called" --answer

tavily "[topic] history original term" --answer

Vocabulary Discovery Process

1. Run initial terminology search:
   bash

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

2. From results, note:
   • Expert terms (technical vocabulary)
   • Outsider terms (popular/introductory language)
   • Cross-domain equivalents
3. Update vocabulary map (template below)
4. Re-run searches with expert terms:
   bash

   tavily "[expert-term]" --answer

5. 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

Question Pattern → Tavily Command

tavily "[expert-term] definition" --answer --depth advanced

tavily "[expert-term] pros cons comparison" --answer

tavily "[claim] evidence research" --answer --depth advanced

tavily "[expert-term] guide tutorial" --answer

tavily "[topic] history origins development" --answer

Source Type Selection

--depth advanced --results 10

--topic general --answer

--topic news --time week

--include [official-domain]

Foundational Search Process

1. Start with expert terminology from Phase 1
2. Run foundational queries:
   bash

   # Definition/overview
   tavily "[expert-term] comprehensive overview" --answer --depth advanced
   
   # Key perspectives
   tavily "[expert-term] major approaches" --answer --results 7

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

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

4. 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

Why Counter-Perspectives Matter

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

Tavily Commands for Counter-Perspectives

tavily "[topic] criticism problems" --answer

tavily "[topic] skeptics critique" --answer

tavily "[topic] alternatives instead of" --answer

tavily "[topic] failures when wrong" --answer

tavily "[topic] debate" --exclude [familiar-sources]

Counter-Perspective Process

1. Identify your current understanding/lean
2. Search for strongest counterargument:
   bash

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

3. Exclude sources you've already seen:
   bash

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

4. Search for failure modes:
   bash

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

5. 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

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

• 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

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

--answer

--depth

basic

advanced

--results

--topic

general

news

finance

--time

day

week

month

year

--include

--exclude

--raw

--json

Scenario → Command Mapping

tavily "query" --answer

tavily "query" --depth advanced --results 10 --answer

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

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

tavily "query" --exclude wikipedia.org

tavily "query" --exclude [already-seen-domains]

tavily "query" --topic finance --answer

tavily "query" --raw --json

Diagnostic States

Quick Diagnostic

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

Anti-Patterns

Output Persistence

Output Discovery

1. Check for

   context/output-config.md

   in the project
2. If found, look for this skill's entry
3. 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
4. Store the user's preference

What to Store

File Naming

{topic}-research-{date}.md

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

Integration Points

Health Check Questions

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

Source Framework

references/research-framework.md