gh-krishagel-geoffrey/skills/research/SKILL.md

name, description, triggers, allowed-tools, version

name	description	triggers	allowed-tools	version
research	Multi-LLM parallel research with query decomposition and synthesis	research find out about investigate look into what do you know about deep dive analyze compare find information learn about	Read, Bash, WebSearch, WebFetch, Task	0.1.0

Research Skill

Discovery-driven, exhaustive research using parallel LLM agents for comprehensive, current information gathering.

Core Principles

CRITICAL: These principles define how research works.

1. Discovery-Driven, Not List-Driven

• Find the BEST sources, not just known sources
• Don't limit to predefined source lists
• The internet is huge - explore it
• Value is in finding what user doesn't already know

2. Context-Aware

• Load user's domain context from preferences
• Research is RELEVANT to their specific situation
• But context doesn't limit WHERE you search

3. Exhaustive

• No time limits - can take 30 minutes to 3 hours
• Don't stop at first page of results
• Keep going until topic is exhausted
• Follow promising links deeper

4. Multimedia

• Not just text articles
• Videos (YouTube), TikTok, podcasts
• Real user experiences from forums

5. Highly Cited

• Every claim must have a citation
• Multiple sources for important claims
• Note when sources conflict

6. Clarifying Questions First

Before diving into research, ask deep, thought-provoking questions to understand:

• What's the actual goal? (not just the surface request)
• What constraints exist? (budget, time, preferences)
• What would success look like?
• What have they already tried or considered?
• Are there hidden requirements?

Example: "Research Japan ski trip" should prompt:

• "What skill level are you and Carrie? Blue runs, black diamonds?"
• "Is après-ski culture important, or pure skiing focus?"
• "Do you need English-friendly areas, or comfortable with Japanese-only?"
• "Any specific dates that are fixed vs flexible?"
• "Besides skiing, anything else you want to do (onsen, food tours)?"

Domain Context Loading

Research automatically loads relevant context from preferences based on detected domain.

How It Works

1. Detect domain from query (travel, shopping, work, etc.)
2. Load research_domains.[domain] from preferences
3. Load referenced context keys
4. Fetch any dynamic data (point balances, etc.)
5. Apply domain-specific research patterns

Available Domains

• travel - Loads loyalty programs, credit cards, ski passes, fetches point balances
• work_education - Loads PSD context, CoSN membership, K-12 patterns
• shopping - Price comparison, quality patterns
• ai_coding - Tech stack, GitHub/HN patterns
• consulting - Strategic recommendations patterns

Dynamic Data Fetching

For travel research, use browser-control to fetch current:

• Marriott points balance
• Alaska miles balance
• Chase points balance
• Active transfer bonus promotions

When to Activate

Use this skill when user needs:

• Current information (credit card perks, travel deals, policies)
• Multi-perspective analysis (comparing options)
• Deep investigation of complex topics
• Fact-checking or verification
• Market research or trend analysis

Travel Research Requirements

CRITICAL: Travel research MUST include user-generated content:

Required Sections for Travel

1. User Reviews - TripAdvisor, FlyerTalk, Reddit feedback
2. "What I Wish I Knew" - Common mistakes and gotchas
3. Real Experiences - Actual trip reports from similar travelers
4. Restaurant/Hotel Reviews - With prices and quality feedback
5. Transportation Tips - Real user experiences with logistics

Sources to Search

• TripAdvisor reviews and forums
• FlyerTalk (for points/miles properties)
• Reddit (r/JapanTravel, r/skiing, r/churning, etc.)
• Ski forums and trip reports
• Points/miles blogs with personal reviews

Browser Access for Deep Research

Use the browser-control skill to scrape full threads and reviews that require:

• JavaScript rendering (Reddit, modern forums)
• Authentication (FlyerTalk, logged-in content)
• Dynamic content loading

Prerequisites:

1. Brave must be running: cd skills/browser-control && ./scripts/launch-chrome.sh
2. User must be logged into relevant sites in the Brave Geoffrey profile

Available Scripts (in skills/browser-control/scripts/):

# Navigate and get page content
bun navigate.js "https://www.reddit.com/r/JapanTravel/comments/..."

# Extract specific content
bun extract.js "https://flyertalk.com/forum/thread" ".post-content" --all

# Search travel sites directly
bun search.js reddit "Hakuba ski resort tips"
bun search.js flyertalk "Marriott Bonvoy Japan redemption"

# Capture current page without navigating
bun capture.js /tmp/screenshot.png

When to Use Browser Control:

• Reddit threads (full comments, not just preview)
• FlyerTalk forum posts (complete thread content)
• Hotel/airline pages requiring login (availability, points pricing)
• Sites that block web scraping but allow browsers

Research Tool Decision Tree

Start with WebSearch/WebFetch for:

• General facts and information
• Blog posts and news articles
• Static content that's publicly accessible
• Quick lookups

Escalate to browser-control when:

• WebFetch returns truncated/incomplete content (JS-rendered sites)
• Need authenticated access (user's Marriott/Alaska account)
• Need real-time prices or availability
• Forum threads show only previews
• Site blocks scraping but allows browsers

Example Flow:

1. User asks: "What do people say about Westin Rusutsu?"
2. Start with WebSearch for blog reviews
3. Find promising Reddit/FlyerTalk threads
4. Use browser-control to get full thread content
5. Synthesize findings with citations

Citation Requirements

CRITICAL: All research output MUST include citations.

Inline Citations

Every factual claim must link to its source:

• "The Westin Rusutsu costs 70,000 points peak (Point Hacks)"
• "Shinkansen to Nagano takes 1.5 hours (Corritrip)"

Source Section

Every research report must end with a complete "Sources" section listing all URLs used.

Why This Matters

• User needs to verify information
• Information changes frequently (credit card perks, prices)
• Establishes credibility
• Allows deeper exploration

No Citation = Don't Include

If you can't cite a source for a claim, either:

1. Find a source
2. Mark it as "unverified"
3. Don't include it

Architecture

Query Decomposition

Break complex questions into 3-7 sub-queries covering different angles:

• Factual/definitional
• Comparative
• Current state
• Expert opinions
• User experiences
• Edge cases

Parallel Agent Execution

Launch multiple researcher agents simultaneously:

• Perplexity - Best for current web information, citations
• Gemini - Good for multi-perspective synthesis
• OpenAI - Strong structured analysis
• Claude - Deep reasoning, nuanced analysis

Result Synthesis

• Collect all findings
• Identify consensus vs conflicts
• Score confidence per finding
• Cite sources
• Provide actionable recommendations

Available Agents

Agents are in ./agents/ directory:

Agent	Best For	API Required
perplexity-researcher.md	Current web info, citations	PERPLEXITY_API_KEY
gemini-researcher.md	Multi-angle comparison	GEMINI_API_KEY
openai-researcher.md	Structured analysis	OPENAI_API_KEY
claude-researcher.md	Deep reasoning	Native (Claude Code)

Usage

Basic Research

User: "Research the best ways to maximize Alaska Airlines miles for Japan flights"

Geoffrey:
1. Decomposes into sub-queries:
   - Current Alaska redemption rates to Japan
   - Partner airline options (JAL, etc.)
   - Sweet spots and award availability patterns
   - Credit card earning strategies
   - Recent devaluations or changes

2. Launches 4 agents in parallel

3. Synthesizes findings with confidence scores

Workflow Command

Use /conduct-research [topic] to trigger full parallel research workflow.

Output Format

## Research: [Topic]

### Context Applied
- Domain: [travel/shopping/work/etc]
- User context loaded: [what was loaded from preferences]
- Dynamic data fetched: [current point balances, etc]

### Executive Summary
[2-3 paragraph overview of key findings and main recommendation]

### Detailed Findings

#### Sub-topic 1
Information with citations throughout. For example, "The Westin Rusutsu
costs 70,000 points peak" ([Point Hacks](url)) and "offers ski-in/ski-out
access" ([Marriott](url)).

#### Sub-topic 2
More information with inline citations...

### Multimedia Resources
- [Video: Title](url) - brief description
- [Podcast: Episode](url) - brief description
- [TikTok: @user](url) - brief description

### What I Discovered You Might Not Know
- Surprising finding 1 that user likely didn't know
- Surprising finding 2
- New source or perspective discovered

### Recommendations
1. Actionable recommendation specific to user's context
2. Another action based on their situation

### Confidence Assessment
- High confidence: [topics with multiple agreeing sources]
- Needs verification: [topics with limited sources]
- Conflicting information: [where sources disagree]

### All Sources
Complete list of every URL referenced:
- [Source Name 1](full-url)
- [Source Name 2](full-url)
- [Source Name 3](full-url)

Note: Every factual claim needs an inline citation. The "All Sources" section at the end provides a consolidated reference list.

Saving Research Reports

ALWAYS save research reports to Google Docs after completing research.

Default Behavior

1. Create Google Doc in Geoffrey/Research folder
2. Use appropriate account (hrg for personal, psd for work)
3. Apply markdown formatting (headers, bold, links)
4. Return link to user

How to Save

cd skills/google-workspace
bun docs/create_doc.js <account> --title "<Research Topic>" --folder Research --content "<markdown>"

Account Selection

• hrg - Personal travel, consulting
• psd - Work-related research
• kh - Personal projects

Future: Obsidian Integration

Will also save to local Obsidian vault (when skill is built).

API Configuration

Keys stored in: ~/Library/Mobile Documents/com~apple~CloudDocs/Geoffrey/secrets/.env

PERPLEXITY_API_KEY=pplx-...
GEMINI_API_KEY=...
OPENAI_API_KEY=sk-...
# Note: Claude runs natively in Claude Code, no API key needed

Performance

• Time: 30 minutes to 3 hours for exhaustive research (not 15-45 seconds)
• Depth: Exhaustive - multiple search pages, follow links, multimedia
• Sources: Discover new sources, not just known lists
• Accuracy: Cross-referenced with confidence scoring, all claims cited

Limitations

• API rate limits may throttle parallel requests
• Costs accrue per API call
• Not all agents may have access to same sources
• Real-time data (stock prices, availability) needs direct API access

Future Enhancements

• Caching frequent research topics
• Learning which agents are best for which domains
• Automatic source credibility scoring
• Research history and versioning