zhongwei/gh-krishagel-geoffrey
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:35:59 +08:00
commit 90883a4d25
287 changed files with 75058 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

181
skills/research/RESEARCH_ENHANCEMENT.md Normal file
View File

@@ -0,0 +1,181 @@
# Research Skill Enhancement - Requirements
## Core Principles
1. **Discovery-driven, not list-driven** - Find best sources wherever they are
2. **Context-aware** - Grounded in user's domain preferences
3. **Finds unknowns** - Value is in discovering what user doesn't know
4. **No time limits** - Can run 30 min to 3 hours
5. **Exhaustive** - Don't stop until topic is exhausted
## Domain Contexts
### What Context Provides
- **Relevance filtering** - what matters to this user
- **Constraint awareness** - their specific resources/limitations
- **Optimization targets** - what to maximize for them
### Domain: Travel
- Loyalty: Alaska MVP Gold 75K, Marriott Titanium Elite
- Points: Current balances (fetch via browser-control)
- Credit cards: Alaska card, Marriott Amex, Chase Sapphire Preferred
- Memberships: Epic Pass
- Preferences: "Luxury at rock-bottom prices", never book only research
### Domain: Shopping
- Quality standards
- Budget ranges
- Brand preferences
### Domain: Work/Education
- PSD context (CIO role)
- UDL expertise
- Edtech landscape
- District priorities
### Domain: AI/Coding
- Tech stack preferences
- Languages/frameworks
- Architecture patterns
### Domain: Consulting
- Service offerings
- Client contexts
## Research Engine Architecture
### Phase 1: Query Understanding
- Detect domain from query
- Load relevant context
- Decompose into sub-questions (5-10 angles)
- Identify what types of sources needed (academic, forum, video, etc.)
### Phase 2: Parallel Multi-Source Discovery
- Launch multiple search strategies simultaneously:
- Multiple search engines (Google, Bing, DuckDuckGo)
- Multiple query formulations
- Different source types (articles, forums, videos, podcasts)
- Use multiple LLMs for different perspectives:
- Perplexity: Current web info with citations
- Gemini: Multi-perspective synthesis
- OpenAI: Structured analysis
- Claude: Deep reasoning
### Phase 3: Source Evaluation & Expansion
- Evaluate each source for:
- Credibility (author expertise, publication reputation)
- Recency (when published/updated)
- Depth (surface vs comprehensive)
- Citations (does it cite others? is it cited?)
- Follow promising leads:
- Sources referenced by good sources
- Authors who appear multiple times
- Cross-referenced claims
### Phase 4: Deep Scraping
- Don't stop at first page of results
- Go 5-10 pages deep on good queries
- Use browser-control for:
- JS-rendered content (Reddit, forums)
- Authenticated pages (user accounts)
- Sites that block scrapers
- Follow internal links on valuable sources
### Phase 5: Multimedia Discovery
- YouTube videos
- TikTok content
- Podcasts (Spotify, Apple)
- Not just text articles
### Phase 6: Synthesis
- Organize by theme/question
- Every claim cited
- Note consensus vs disagreement
- Include multimedia resources
- Provide actionable recommendations
- Flag what's still uncertain
## Output Format
```markdown
## Research: [Topic]
### Context Applied
- [Domain context that was loaded]
- [Dynamic data fetched - e.g., current point balances]
### Executive Summary
[2-3 paragraph overview of key findings]
### Detailed Findings
#### [Sub-topic 1]
[Deep analysis with inline citations]
#### [Sub-topic 2]
[Deep analysis with inline citations]
### Multimedia Resources
- [Video: Title](url) - description
- [Podcast: Title](url) - description
- [TikTok: @user](url) - description
### Recommendations
1. [Actionable recommendation based on user's context]
2. [Another recommendation]
### What I Discovered You Might Not Know
- [Surprising finding 1]
- [Surprising finding 2]
### Confidence Assessment
- High confidence: [topics]
- Needs verification: [topics]
- Conflicting information: [topics]
### All Sources
[Complete list of every URL referenced]
```
## Technical Implementation
### Files to Create/Modify
- [ ] Update preferences.json with domain contexts
- [ ] Create domain context loader
- [ ] Create multi-LLM research orchestrator
- [ ] Create source evaluator
- [ ] Create deep scraper (uses browser-control)
- [ ] Create multimedia searcher
- [ ] Create synthesis engine
- [ ] Update SKILL.md with new architecture
### API Keys Needed
- PERPLEXITY_API_KEY
- GEMINI_API_KEY
- OPENAI_API_KEY
- (Claude runs natively)
### Browser-Control Integration
- Fetch current balances (Marriott, Alaska, Chase)
- Scrape full forum threads
- Access authenticated content
- Handle JS-rendered sites
## Success Criteria
1. Can run a travel research query and get:
- Current point balances fetched
- Transfer bonus opportunities identified
- 5-6 hotel options with points AND cash prices
- Flight options with miles needed
- Deep user reviews from forums
- Video content discovered
- Optimization recommendations
2. Report takes 30-60 minutes to generate (not 5 minutes)
3. Sources include things user didn't know existed
4. Every claim is cited
5. Recommendations are specific to user's context

364
skills/research/SKILL.md Normal file
View File

@@ -0,0 +1,364 @@
---
name: research
description: Multi-LLM parallel research with query decomposition and synthesis
triggers:
- "research"
- "find out about"
- "investigate"
- "look into"
- "what do you know about"
- "deep dive"
- "analyze"
- "compare"
- "find information"
- "learn about"
allowed-tools: Read, Bash, WebSearch, WebFetch, Task
version: 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/`):
```bash
# 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](url))"
- "Shinkansen to Nagano takes 1.5 hours ([Corritrip](url))"
### 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
```markdown
## 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
```bash
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`
```bash
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

91
skills/research/agents/claude-researcher.md Normal file
View File

@@ -0,0 +1,91 @@
# Claude Researcher Agent
You are a research specialist using Claude's native capabilities for deep reasoning and nuanced analysis.
## Strengths
- Deep reasoning and analysis
- Nuanced understanding of context
- Strong at identifying implications
- Excellent at synthesis and recommendations
## Best For
- Complex, multi-faceted questions
- "What should I do" recommendations
- Understanding implications and consequences
- Synthesizing information into actionable insights
## Execution
This agent runs natively within Claude Code - no external API call needed.
When given a research query:
1. **Use Built-in Tools**
- WebSearch for current information
- WebFetch for specific page content
- Task tool for parallel sub-queries if needed
2. **Deep Analysis Approach**
- Consider the question from multiple angles
- Identify unstated assumptions
- Consider edge cases and exceptions
- Think about implications and consequences
3. **Synthesize and Recommend**
- Combine findings into coherent narrative
- Weigh trade-offs explicitly
- Provide actionable recommendations
- Note confidence levels
## Output Format
```markdown
## Claude Research Results
### Query
[The specific question researched]
### Analysis
#### Context
[Background and framing]
#### Key Findings
1. **Finding 1**: [Detail]
- Implication: ...
- Confidence: High/Medium/Low
2. **Finding 2**: [Detail]
- Implication: ...
- Confidence: High/Medium/Low
#### Nuances
- Important exceptions or edge cases
- When this advice might not apply
- Assumptions being made
### Recommendations
**Primary Recommendation**
[What to do and why]
**Alternatives**
- Option B: [When this might be better]
- Option C: [When this might be better]
### Confidence Assessment
- What I'm confident about: ...
- What's uncertain: ...
- What needs more research: ...
### Sources
- [Source](url) - What it contributed
```
## Important
- Think deeply before responding
- Consider the user's specific context (Hagel's preferences)
- Be explicit about confidence levels
- Provide actionable recommendations, not just information
- Don't hedge excessively - give clear guidance when possible

91
skills/research/agents/gemini-researcher.md Normal file
View File

@@ -0,0 +1,91 @@
# Gemini Researcher Agent
You are a research specialist using Google Gemini for multi-perspective analysis.
## Strengths
- Multi-angle investigation
- Good at comparisons and trade-offs
- Access to Google's knowledge
- Strong at synthesizing diverse viewpoints
## Best For
- "Compare X vs Y" questions
- Pros/cons analysis
- Market comparisons
- Understanding different perspectives
## Execution
When given a research query:
1. **Load API Key**
```bash
source ~/Library/Mobile\ Documents/com~apple~CloudDocs/Geoffrey/secrets/.env
```
2. **Execute Gemini Query**
Use the Gemini API for research.
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro:generateContent?key=$GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{
"parts": [{
"text": "Research the following topic thoroughly, providing multiple perspectives and trade-offs: YOUR_QUERY_HERE"
}]
}],
"generationConfig": {
"temperature": 0.7,
"maxOutputTokens": 4096
}
}'
```
3. **Extract and Format Results**
- Identify different perspectives
- Note trade-offs and considerations
- Highlight consensus points
- Flag controversial or debated aspects
## Output Format
```markdown
## Gemini Research Results
### Query
[The specific question researched]
### Perspectives
**Perspective 1: [Name/Angle]**
- Key points
- Supporting evidence
**Perspective 2: [Name/Angle]**
- Key points
- Supporting evidence
### Trade-offs
| Option | Pros | Cons |
|--------|------|------|
| A | ... | ... |
| B | ... | ... |
### Consensus Points
- What most sources agree on
### Debated Points
- Where opinions differ and why
### Notes
- Limitations of this analysis
- Areas needing deeper investigation
```
## Important
- Present multiple viewpoints fairly
- Don't favor one perspective without evidence
- Note when something is opinion vs fact
- Identify areas of genuine uncertainty

94
skills/research/agents/openai-researcher.md Normal file
View File

@@ -0,0 +1,94 @@
# OpenAI Researcher Agent
You are a research specialist using OpenAI GPT-4 for structured analysis and reasoning.
## Strengths
- Structured, systematic analysis
- Strong at categorization and frameworks
- Good at step-by-step reasoning
- Excellent at summarization
## Best For
- "How does X work" questions
- Process and workflow analysis
- Creating frameworks and mental models
- Structured comparisons
## Execution
When given a research query:
1. **Load API Key**
```bash
source ~/Library/Mobile\ Documents/com~apple~CloudDocs/Geoffrey/secrets/.env
```
2. **Execute OpenAI Query**
Use the OpenAI API for research.
```bash
curl -X POST "https://api.openai.com/v1/chat/completions" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4-turbo-preview",
"messages": [
{"role": "system", "content": "You are a research analyst. Provide structured, systematic analysis with clear categorization and frameworks. Break down complex topics into understandable components."},
{"role": "user", "content": "YOUR_QUERY_HERE"}
],
"temperature": 0.7,
"max_tokens": 4096
}'
```
3. **Extract and Format Results**
- Create clear structure/framework
- Break into logical categories
- Provide step-by-step explanations
- Summarize key takeaways
## Output Format
```markdown
## OpenAI Research Results
### Query
[The specific question researched]
### Framework/Structure
#### Category 1: [Name]
- Key point A
- Key point B
- How it relates to other categories
#### Category 2: [Name]
- Key point A
- Key point B
### Process/Workflow
1. Step one
2. Step two
3. Step three
### Key Concepts
| Concept | Definition | Relevance |
|---------|------------|-----------|
| X | ... | ... |
| Y | ... | ... |
### Summary
[Concise summary of findings]
### Notes
- Assumptions made
- Limitations of this framework
- When this analysis might not apply
```
## Important
- Prioritize clarity and structure
- Use frameworks when helpful
- Break complex topics into digestible parts
- Be explicit about assumptions

76
skills/research/agents/perplexity-researcher.md Normal file
View File

@@ -0,0 +1,76 @@
# Perplexity Researcher Agent
You are a research specialist using Perplexity AI for web-based information gathering.
## Strengths
- Current web information with citations
- Real-time data and recent changes
- Source attribution
- Fact-checking against live sources
## Best For
- "What are the current..." questions
- Policy changes and updates
- Recent news and announcements
- Verification of claims
## Execution
When given a research query:
1. **Load API Key**
```bash
source ~/Library/Mobile\ Documents/com~apple~CloudDocs/Geoffrey/secrets/.env
```
2. **Execute Perplexity Query**
Use the Perplexity API to search for current information.
```bash
curl -X POST "https://api.perplexity.ai/chat/completions" \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "llama-3.1-sonar-large-128k-online",
"messages": [
{"role": "system", "content": "You are a research assistant. Provide detailed, factual information with source citations. Focus on current, accurate data."},
{"role": "user", "content": "YOUR_QUERY_HERE"}
]
}'
```
3. **Extract and Format Results**
- Pull out key facts
- Note all source URLs
- Flag any conflicting information
- Note publication dates
## Output Format
```markdown
## Perplexity Research Results
### Query
[The specific question researched]
### Findings
- Fact 1 [Source](url)
- Fact 2 [Source](url)
- etc.
### Key Sources
1. [Source Name](url) - Date accessed
2. [Source Name](url) - Date accessed
### Notes
- Any caveats or limitations
- Conflicting information found
- Areas needing further research
```
## Important
- Always include source citations
- Note when information might be outdated
- Flag paywalled or inaccessible sources
- Distinguish facts from opinions

122
skills/research/commands/conduct-research.md Normal file
View File

@@ -0,0 +1,122 @@
# Conduct Research Command
Orchestrate parallel multi-LLM research on a topic.
## Usage
```
/conduct-research [topic or question]
```
## Workflow
### Step 1: Query Decomposition
Break the research topic into 3-7 focused sub-queries. Consider:
- **Factual**: What are the basic facts?
- **Current**: What's the latest information?
- **Comparative**: How does it compare to alternatives?
- **Practical**: How does it work in practice?
- **Optimization**: What are the best strategies?
- **Gotchas**: What are common mistakes or pitfalls?
Example for "maximize Alaska Airlines miles for Japan":
1. Current Alaska redemption rates to Japan partners
2. JAL vs Cathay vs other OneWorld options for Japan routes
3. Best credit card strategies for earning Alaska miles
4. Award availability patterns and booking tips
5. Recent program changes or devaluations
### Step 2: Parallel Agent Execution
Launch researcher agents in parallel using the Task tool. Each agent gets relevant sub-queries:
**Perplexity Agent** (current info)
- Sub-queries about recent changes, current rates, latest news
**Gemini Agent** (comparisons)
- Sub-queries comparing options, trade-offs
**OpenAI Agent** (structure)
- Sub-queries about processes, frameworks, how things work
**Claude Agent** (synthesis)
- Sub-queries about recommendations, implications
Use this pattern:
```
Launch 4 Task agents in parallel:
- Task: perplexity-researcher with [sub-queries 1, 2]
- Task: gemini-researcher with [sub-queries 3, 4]
- Task: openai-researcher with [sub-query 5]
- Task: claude-researcher with [synthesis query]
```
### Step 3: Result Collection
Gather results from all agents (typically 15-45 seconds).
### Step 4: Synthesis
Combine all findings into a cohesive report:
1. **Identify Consensus** - What do multiple sources agree on?
2. **Flag Conflicts** - Where do sources disagree?
3. **Score Confidence** - High (4/4 agree), Medium (3/4), Low (2/4 or conflicting)
4. **Extract Actions** - What should the user actually do?
### Step 5: Final Report
Format output as:
```markdown
## Research Report: [Topic]
### Executive Summary
[2-3 sentence overview of key findings]
### Key Findings
#### High Confidence (Multiple Sources Agree)
- Finding 1
- Finding 2
#### Medium Confidence
- Finding 3
- Finding 4
#### Needs Verification
- Finding 5 (sources conflict)
### Detailed Analysis
[Organized by sub-topic with source attribution]
### Sources
- [Source 1](url) - via Perplexity
- [Source 2](url) - via Gemini
- etc.
### Recommendations
1. **Do This First**: [Action]
2. **Then Consider**: [Action]
3. **Watch Out For**: [Gotcha]
### Research Metadata
- Agents used: Perplexity, Gemini, OpenAI, Claude
- Time: [X seconds]
- Date: [Today's date]
- Confidence: Overall High/Medium/Low
```
## API Requirements
Ensure these are configured in `~/Library/Mobile Documents/com~apple~CloudDocs/Geoffrey/secrets/.env`:
- PERPLEXITY_API_KEY
- GEMINI_API_KEY
- OPENAI_API_KEY
## Notes
- If an API fails, continue with remaining agents
- Note which agents were used in final report
- For time-sensitive topics, prioritize Perplexity results
- Consider user preferences when making recommendations (check knowledge-manager)

117
skills/research/scripts/context-loader.js Normal file
View File

@@ -0,0 +1,117 @@
#!/usr/bin/env bun
/**
* Domain Context Loader
*
* Loads relevant user context from preferences based on detected research domain.
*
* Usage: bun context-loader.js <domain>
*
* Domains: travel, work_education, shopping, ai_coding, consulting
*/
import fs from 'fs';
import path from 'path';
const PREFERENCES_PATH = path.join(
process.env.HOME,
'Library/Mobile Documents/com~apple~CloudDocs/Geoffrey/knowledge/preferences.json'
);
function loadPreferences() {
const content = fs.readFileSync(PREFERENCES_PATH, 'utf-8');
return JSON.parse(content);
}
function getNestedValue(obj, keyPath) {
return keyPath.split('.').reduce((current, key) => {
return current && current[key] !== undefined ? current[key] : null;
}, obj);
}
function detectDomain(query) {
const queryLower = query.toLowerCase();
const domainPatterns = {
travel: ['trip', 'vacation', 'hotel', 'flight', 'points', 'miles', 'ski', 'travel', 'resort', 'airline', 'marriott', 'alaska'],
work_education: ['school', 'district', 'education', 'udl', 'learning', 'student', 'teacher', 'psd', 'k-12', 'iste', 'cosn'],
shopping: ['buy', 'purchase', 'product', 'review', 'price', 'deal', 'compare', 'best', 'recommend'],
ai_coding: ['code', 'programming', 'api', 'framework', 'library', 'github', 'ai', 'llm', 'model', 'development'],
consulting: ['strategy', 'client', 'engagement', 'project', 'consulting', 'advisory']
};
for (const [domain, patterns] of Object.entries(domainPatterns)) {
if (patterns.some(p => queryLower.includes(p))) {
return domain;
}
}
return 'general';
}
function loadDomainContext(domain, preferences) {
const domainConfig = preferences.preferences.research_domains?.[domain];
if (!domainConfig) {
return {
domain,
context: {},
patterns: [],
dynamic_data: []
};
}
// Load context from specified keys
const context = {};
for (const keyPath of domainConfig.context_keys || []) {
const value = getNestedValue(preferences.preferences, keyPath);
if (value) {
context[keyPath] = value;
}
}
return {
domain,
context,
patterns: domainConfig.research_patterns || [],
dynamic_data: domainConfig.fetch_dynamic || []
};
}
async function main() {
const args = process.argv.slice(2);
const domainOrQuery = args.join(' ');
if (!domainOrQuery) {
console.error(JSON.stringify({
error: 'Missing domain or query',
usage: 'bun context-loader.js <domain or query>',
domains: ['travel', 'work_education', 'shopping', 'ai_coding', 'consulting']
}));
process.exit(1);
}
try {
const preferences = loadPreferences();
// Check if it's a known domain name or a query to detect from
const knownDomains = ['travel', 'work_education', 'shopping', 'ai_coding', 'consulting'];
const domain = knownDomains.includes(domainOrQuery.toLowerCase())
? domainOrQuery.toLowerCase()
: detectDomain(domainOrQuery);
const result = loadDomainContext(domain, preferences);
console.log(JSON.stringify(result, null, 2));
} catch (error) {
console.error(JSON.stringify({
error: error.message
}));
process.exit(1);
}
}
main();
module.exports = { loadPreferences, detectDomain, loadDomainContext };

263
skills/research/scripts/orchestrator.js Normal file
View File

@@ -0,0 +1,263 @@
#!/usr/bin/env bun
/**
* Deep Research Orchestrator
*
* Architecture based on current best practices:
* - Single agent with iterative deepening
* - Search → Summarize → Compress → Report
* - Specialized models for different steps
* - Cross-validation and reflection
*
* Sources:
* - https://arxiv.org/abs/2506.18096 (Deep Research Agents survey)
* - https://github.com/langchain-ai/open_deep_research
* - https://openai.com/index/introducing-deep-research/
*
* Usage: bun orchestrator.js --query "Research topic" [--domain travel]
*/
import fs from 'fs';
import path from 'path';
const SECRETS_PATH = path.join(
process.env.HOME,
'Library/Mobile Documents/com~apple~CloudDocs/Geoffrey/secrets/.env'
);
// Load environment variables
function loadEnv() {
if (fs.existsSync(SECRETS_PATH)) {
const content = fs.readFileSync(SECRETS_PATH, 'utf-8');
for (const line of content.split('\n')) {
const [key, ...valueParts] = line.split('=');
if (key && valueParts.length) {
process.env[key.trim()] = valueParts.join('=').trim();
}
}
}
}
loadEnv();
/**
* Phase 1: Query Decomposition
* Break research topic into 5-10 sub-questions from different angles
*/
async function decomposeQuery(topic, context) {
// This would ideally call an LLM, but we can structure it deterministically
const angles = [
'factual/definitional',
'comparative/alternatives',
'current state/latest developments',
'expert opinions/professional sources',
'user experiences/reviews',
'common problems/gotchas',
'optimization/best practices',
'multimedia/visual resources'
];
const subQueries = angles.map(angle => ({
angle,
query: `${topic} - ${angle}`,
priority: angle.includes('user') || angle.includes('current') ? 'high' : 'normal'
}));
return {
mainTopic: topic,
context,
subQueries,
timestamp: new Date().toISOString()
};
}
/**
* Phase 2: Parallel Search
* Execute multiple searches simultaneously
*/
async function executeSearches(decomposition) {
const results = [];
// In full implementation, this would:
// 1. Call WebSearch for each sub-query
// 2. Use multiple search engines
// 3. Try different query formulations
// 4. Launch browser-control for JS-heavy sites
for (const sq of decomposition.subQueries) {
results.push({
angle: sq.angle,
query: sq.query,
sources: [], // Would be populated by actual searches
status: 'pending'
});
}
return results;
}
/**
* Phase 3: Deep Scraping
* Use browser-control to get full content from promising sources
*/
async function deepScrape(searchResults) {
// Would call browser-control scripts for:
// - Reddit threads (full comments)
// - FlyerTalk forum posts
// - Sites that block scrapers
// - Authenticated content
return {
scraped: [],
skipped: [],
errors: []
};
}
/**
* Phase 4: Summarization
* Compress each source into key findings
*/
async function summarizeFindings(sources) {
// Would use a smaller model (gpt-4o-mini) to summarize each source
// Extract: key claims, supporting evidence, credibility signals
return {
summaries: [],
totalSources: sources.length
};
}
/**
* Phase 5: Cross-Validation
* Check claims across sources, identify consensus vs conflicts
*/
async function crossValidate(summaries) {
// Compare claims across sources
// Identify: consensus, conflicts, unique findings
return {
consensus: [],
conflicts: [],
unique: []
};
}
/**
* Phase 6: Report Generation
* Synthesize everything into final report
*/
async function generateReport(topic, context, validated) {
const report = {
title: `Research: ${topic}`,
generatedAt: new Date().toISOString(),
context: {
domain: context.domain,
loaded: Object.keys(context.context),
patterns: context.patterns
},
executiveSummary: '',
detailedFindings: [],
multimediaResources: [],
discoveries: [], // "What I discovered you might not know"
recommendations: [],
confidence: {
high: [],
needsVerification: [],
conflicting: []
},
sources: []
};
return report;
}
/**
* Main Orchestration Loop
*/
async function runDeepResearch(topic, options = {}) {
console.error('🔍 Starting deep research...');
console.error(`📋 Topic: ${topic}`);
// Load context
const { loadDomainContext, detectDomain, loadPreferences } = require('./context-loader.js');
const preferences = loadPreferences();
const domain = options.domain || detectDomain(topic);
const context = loadDomainContext(domain, preferences);
console.error(`🏷️ Detected domain: ${domain}`);
console.error(`📦 Context loaded: ${Object.keys(context.context).length} keys`);
// Phase 1: Decompose
console.error('\n📝 Phase 1: Decomposing query...');
const decomposition = await decomposeQuery(topic, context);
console.error(` Generated ${decomposition.subQueries.length} sub-queries`);
// Phase 2: Search
console.error('\n🔎 Phase 2: Executing parallel searches...');
const searchResults = await executeSearches(decomposition);
console.error(` Searched ${searchResults.length} angles`);
// Phase 3: Deep Scrape
console.error('\n🌐 Phase 3: Deep scraping promising sources...');
const scraped = await deepScrape(searchResults);
console.error(` Scraped ${scraped.scraped.length} sources`);
// Phase 4: Summarize
console.error('\n📋 Phase 4: Summarizing findings...');
const summaries = await summarizeFindings([...searchResults, ...scraped.scraped]);
console.error(` Summarized ${summaries.totalSources} sources`);
// Phase 5: Cross-validate
console.error('\n✅ Phase 5: Cross-validating claims...');
const validated = await crossValidate(summaries);
console.error(` Found ${validated.consensus.length} consensus, ${validated.conflicts.length} conflicts`);
// Phase 6: Generate report
console.error('\n📄 Phase 6: Generating report...');
const report = await generateReport(topic, context, validated);
return report;
}
// CLI interface
async function main() {
const args = process.argv.slice(2);
let topic = '';
let domain = null;
for (let i = 0; i < args.length; i++) {
if (args[i] === '--query') {
topic = args[++i];
} else if (args[i] === '--domain') {
domain = args[++i];
} else if (!args[i].startsWith('--')) {
topic = args.slice(i).join(' ');
break;
}
}
if (!topic) {
console.error(JSON.stringify({
error: 'Missing research topic',
usage: 'bun orchestrator.js --query "Research topic" [--domain travel]'
}));
process.exit(1);
}
try {
const report = await runDeepResearch(topic, { domain });
console.log(JSON.stringify(report, null, 2));
} catch (error) {
console.error(JSON.stringify({
error: error.message,
stack: error.stack
}));
process.exit(1);
}
}
main();
module.exports = { runDeepResearch, decomposeQuery };