SuperClaude/research/index.ts

/**
 * Research Agent - Deep web research with adaptive planning
 *
 * Features:
 * - Adaptive depth control (quick, standard, deep, exhaustive)
 * - Parallel-first search execution
 * - Multi-hop exploration
 * - Evidence-based synthesis
 *
 * MCP Integration:
 * - Tavily: Primary search and extraction
 * - Sequential: Complex reasoning
 * - Playwright: JavaScript-heavy content
 * - Serena: Session persistence
 */

export interface ResearchOptions {
  query: string;
  depth?: 'quick' | 'standard' | 'deep' | 'exhaustive';
  strategy?: 'planning' | 'intent' | 'unified';
}

export interface ResearchResult {
  summary: string;
  sources: Source[];
  confidence: number;
  timestamp: string;
}

interface Source {
  url: string;
  title: string;
  excerpt: string;
  credibility: number;
}

/**
 * Execute deep research
 *
 * Flow:
 * 1. Understand (5-10% effort)
 * 2. Plan (10-15% effort)
 * 3. TodoWrite (5% effort)
 * 4. Execute (50-60% effort)
 * 5. Track (Continuous)
 * 6. Validate (10-15% effort)
 *
 * @param options - Research configuration
 * @returns Research results with sources
 */
export async function research(options: ResearchOptions): Promise<ResearchResult> {
  const { query, depth = 'standard', strategy = 'unified' } = options;

  console.log(`🔍 Starting ${depth} research: ${query}`);
  console.log(`📊 Strategy: ${strategy}`);
  console.log("");

  // 1. Understand (5-10% effort)
  const context = await understand(query);
  console.log(`✅ Understanding complete (complexity: ${context.complexity})`);

  // 2. Plan (10-15% effort)
  const plan = await createPlan(context, depth, strategy);
  console.log(`✅ Research plan created (${plan.tasks.length} tasks)`);

  // 3. TodoWrite (5% effort)
  console.log(`📝 Creating task list...`);
  // TodoWrite integration would go here

  // 4. Execute (50-60% effort)
  console.log(`🚀 Executing research...`);
  const results = await execute(plan);

  // 5. Validate (10-15% effort)
  console.log(`🔍 Validating results...`);
  const validated = await validate(results);

  // 6. Generate report
  const report = await generateReport(validated, query, depth);

  return report;
}

/**
 * Phase 1: Understand query
 */
async function understand(query: string): Promise<any> {
  return {
    query,
    complexity: assessComplexity(query),
    requiredInformation: identifyRequirements(query),
    resourceNeeds: 'web_search',
    successCriteria: ['evidence', 'credibility', 'completeness']
  };
}

function assessComplexity(query: string): 'simple' | 'moderate' | 'complex' {
  // Heuristic: word count, question type, etc.
  if (query.length < 50) return 'simple';
  if (query.length < 150) return 'moderate';
  return 'complex';
}

function identifyRequirements(query: string): string[] {
  // Identify what type of information is needed
  return ['facts', 'sources', 'analysis'];
}

/**
 * Phase 2: Create research plan
 */
async function createPlan(context: any, depth: string, strategy: string): Promise<any> {
  const hops = getHopCount(depth);

  return {
    strategy,
    tasks: generateTasks(context, hops),
    parallelizationPlan: identifyParallelTasks(context),
    milestones: createMilestones(hops)
  };
}

function getHopCount(depth: string): number {
  const hopMap = {
    'quick': 1,
    'standard': 2-3,
    'deep': 3-4,
    'exhaustive': 5
  };
  return hopMap[depth] || 2;
}

function generateTasks(context: any, hops: number): any[] {
  // Generate research tasks based on context and depth
  return [];
}

function identifyParallelTasks(context: any): any[] {
  // Identify which searches can run in parallel
  return [];
}

function createMilestones(hops: number): string[] {
  return [`Complete hop ${hop}` for (let hop = 1; hop <= hops; hop++)];
}

/**
 * Phase 4: Execute research
 */
async function execute(plan: any): Promise<any> {
  // Execute searches (parallel-first approach)
  // This would integrate with Tavily MCP, WebSearch, etc.

  return {
    findings: [],
    sources: [],
    confidence: 0.8
  };
}

/**
 * Phase 5: Validate results
 */
async function validate(results: any): Promise<any> {
  // Verify evidence chains
  // Check source credibility
  // Resolve contradictions
  // Ensure completeness

  return {
    ...results,
    validated: true,
    contradictions: [],
    gaps: []
  };
}

/**
 * Phase 6: Generate report
 */
async function generateReport(data: any, query: string, depth: string): Promise<ResearchResult> {
  const timestamp = new Date().toISOString();
  const filename = `docs/research/${slugify(query)}_${timestamp.split('T')[0]}.md`;

  console.log(`💾 Saving report to: ${filename}`);

  return {
    summary: `Research on: ${query}`,
    sources: data.sources || [],
    confidence: data.confidence || 0.8,
    timestamp
  };
}

function slugify(text: string): string {
  return text.toLowerCase().replace(/[^a-z0-9]+/g, '_');
}

/**
 * Adaptive depth examples
 */
export const examples = {
  quick: "/research 'latest quantum computing news' --depth quick",
  standard: "/research 'competitive analysis of AI coding assistants'",
  deep: "/research 'distributed systems best practices' --depth deep",
  exhaustive: "/research 'self-improving AI agents' --depth exhaustive"
};