research

name	research
description	Research best practices for tech stacks and product domains using Context7 or WebSearch

Research Skill

Enables agents to research current best practices, design patterns, and implementation approaches for technologies and product domains.

When to Use

• Tech Stack Analysis: Learning current best practices for detected frameworks/languages
• Domain Patterns: Understanding implementation approaches for specific business domains
• Agent Generation: Informing specialized agent creation with research findings
• Architecture Decisions: Comparing approaches before implementation
• Trend Analysis: Understanding what's current vs deprecated

Available Research Methods

1. Context7 MCP (Preferred)

Context7 provides curated, high-quality technical documentation and best practices.

Advantages:

• ✅ Curated, accurate results
• ✅ Up-to-date framework documentation
• ✅ Language-specific patterns
• ✅ Faster than web search
• ✅ No noise or outdated content

Check Availability:

function hasContext7() {
  // Check if Context7 MCP is connected
  // Claude Code automatically exposes MCP tools
  return typeof mcp__context7__search !== 'undefined';
}

Usage:

// Example: Research Next.js 15 patterns
const results = await mcp__context7__search({
  query: 'Next.js 15 app router best practices',
  limit: 5
});

// Results include:
// - Official documentation
// - Verified patterns
// - Current recommendations

2. WebSearch (Fallback)

When Context7 is unavailable, use WebSearch for broader coverage.

Advantages:

• ✅ Always available
• ✅ Broader coverage (blogs, forums, etc.)
• ✅ Real-world examples
• ✅ Community insights

Limitations:

• ⚠️ May include outdated content
• ⚠️ Requires filtering and verification
• ⚠️ More noise

Usage:

const results = await WebSearch({
  query: 'Next.js 15 app router best practices 2026',
  limit: 5
});

// Always include current year in query for freshness

Research Workflow

Step 1: Determine Research Method

const researchMethod = hasContext7() ? 'context7' : 'websearch';

console.log(`Research method: ${researchMethod}`);

Step 2: Formulate Queries

Create specific, targeted queries:

Good queries:

• "Next.js 15 server components best practices"
• "React 19 concurrent rendering patterns"
• "PostgreSQL connection pooling with Prisma"
• "Authentication implementation patterns 2026"

Bad queries:

• "Next.js" (too broad)
• "How to code" (too generic)
• "Best JavaScript framework" (subjective, not actionable)

Query Template:

[Technology/Framework] + [Specific Topic] + [Year]

Step 3: Execute Research

async function researchTopic(topic, context = {}) {
  const queries = generateQueries(topic, context);
  const findings = [];

  for (const query of queries) {
    let result;

    if (hasContext7()) {
      result = await mcp__context7__search({
        query,
        limit: 3
      });
    } else {
      result = await WebSearch({
        query: `${query} ${new Date().getFullYear()}`,
        limit: 3
      });
    }

    findings.push({
      query,
      results: result,
      source: hasContext7() ? 'context7' : 'websearch'
    });
  }

  return findings;
}

Step 4: Synthesize Findings

Extract actionable insights from research results:

function synthesizeResearch(findings, context) {
  // Aggregate findings by category
  const synthesis = {
    techStackPatterns: {},
    domainPatterns: {},
    bestPractices: [],
    commonPitfalls: [],
    references: []
  };

  for (const finding of findings) {
    // Extract tech stack patterns
    if (finding.query.includes(context.techStack.framework)) {
      synthesis.techStackPatterns[context.techStack.framework] = extractPatterns(finding.results);
    }

    // Extract domain-specific patterns
    for (const domain of context.domains || []) {
      if (finding.query.includes(domain)) {
        synthesis.domainPatterns[domain] = extractPatterns(finding.results);
      }
    }

    // Collect best practices
    synthesis.bestPractices.push(...extractBestPractices(finding.results));

    // Collect common pitfalls
    synthesis.commonPitfalls.push(...extractPitfalls(finding.results));

    // Store references
    synthesis.references.push({
      query: finding.query,
      source: finding.source,
      url: extractURL(finding.results)
    });
  }

  // Deduplicate and rank
  synthesis.bestPractices = deduplicateAndRank(synthesis.bestPractices);
  synthesis.commonPitfalls = deduplicateAndRank(synthesis.commonPitfalls);

  return synthesis;
}

Research Use Cases

Use Case 1: Tech Stack Research

Research current best practices for detected technologies:

// Called by /agentful-generate after tech stack detection
const techStack = {
  framework: 'Next.js',
  version: '15.1.0',
  language: 'TypeScript',
  database: 'PostgreSQL',
  orm: 'Prisma'
};

const queries = [
  `${techStack.framework} ${techStack.version} best practices`,
  `${techStack.framework} project structure patterns`,
  `${techStack.orm} with ${techStack.database} optimization`,
  `TypeScript configuration for ${techStack.framework}`
];

const findings = await researchTopic('tech-stack', { techStack, queries });
const synthesis = synthesizeResearch(findings, { techStack });

// Use synthesis to inform:
// - Agent generation (what agents should know)
// - Skill creation (patterns to document)
// - Architecture decisions

Use Case 2: Domain Research

Research implementation patterns for product domains:

// Called by /agentful-generate after domain discovery
const product = {
  type: 'task management app',
  domains: ['authentication', 'tasks', 'collaboration']
};

const queries = [
  `${product.type} architecture patterns`,
  `authentication implementation best practices ${techStack.framework}`,
  `task management data model design`,
  `real-time collaboration implementation`
];

const findings = await researchTopic('domains', { product, queries });
const synthesis = synthesizeResearch(findings, { domains: product.domains });

// Use synthesis to inform:
// - Domain agent specialization
// - Database schema design
// - API design patterns

Use Case 3: Pre-Implementation Research

Research before implementing a complex feature:

// Called by orchestrator before delegating complex work
const feature = {
  name: 'Real-time notifications',
  complexity: 'high',
  technologies: ['WebSockets', 'Redis', 'React']
};

const queries = [
  `WebSocket implementation ${techStack.framework}`,
  `Redis pub/sub patterns for notifications`,
  `React real-time updates best practices`,
  `scaling WebSocket connections`
];

const findings = await researchTopic('feature', { feature, queries });
const synthesis = synthesizeResearch(findings, { feature });

// Share findings with specialist agent before implementation

Quality Criteria

When evaluating research findings:

1. Recency: Prefer results from current year
2. Authority: Official docs > verified blogs > forums
3. Specificity: Specific patterns > general advice
4. Actionability: Code examples > theory
5. Relevance: Exact version match > general version

Integration Points

/agentful-generate

Research is integrated into agent generation:

// Step 3 of /agentful-generate workflow
console.log('Researching best practices...');

const research = await researchTopic('generation', {
  techStack,
  domains,
  productType
});

const synthesis = synthesizeResearch(research, { techStack, domains });

// Use synthesis when generating:
// - Domain agent responsibilities
// - Tech skill documentation
// - Best practices sections

Orchestrator

Research can inform architectural decisions:

// Before implementing complex features
if (feature.complexity === 'high') {
  console.log(`Researching implementation approaches for ${feature.name}...`);

  const research = await researchTopic('feature-planning', {
    feature,
    techStack
  });

  const synthesis = synthesizeResearch(research, { feature });

  // Present findings to user for decision
  AskUserQuestion({
    question: `
Research findings for ${feature.name}:

Recommended approach:
${synthesis.bestPractices[0]}

Alternatives:
${synthesis.bestPractices.slice(1, 3).join('\n')}

Which approach should we use?
`,
    options: synthesis.bestPractices.map(p => p.summary)
  });
}

Example: Full Research Flow

// 1. Detect tech stack
const techStack = detectTechStack();

// 2. Read product requirements
const product = Read('.claude/product/index.md');
const productType = extractProductType(product);
const domains = extractDomains(product);

// 3. Research
console.log('Researching best practices...');

const method = hasContext7() ? 'Context7' : 'WebSearch';
console.log(`Method: ${method}`);

// Tech stack research
const techResearch = await researchTopic('tech-stack', {
  techStack,
  queries: [
    `${techStack.framework} ${techStack.version} best practices`,
    `${techStack.framework} project structure`,
    `${techStack.orm} patterns`
  ]
});

// Domain research
const domainResearch = await researchTopic('domains', {
  domains,
  queries: domains.map(d => `${d} domain implementation patterns`)
});

// Product type research
const productResearch = await researchTopic('product-type', {
  productType,
  queries: [`${productType} application architecture`]
});

// 4. Synthesize
const synthesis = synthesizeResearch(
  [...techResearch, ...domainResearch, ...productResearch],
  { techStack, domains, productType }
);

// 5. Apply findings
console.log('Research complete. Applying findings to agent generation...');

// Generate agents with research-informed patterns
generateAgentsWithResearch(synthesis);

Error Handling

async function safeResearch(query, context = {}) {
  try {
    if (hasContext7()) {
      return await mcp__context7__search({ query, limit: 3 });
    } else {
      return await WebSearch({ query: `${query} ${new Date().getFullYear()}`, limit: 3 });
    }
  } catch (error) {
    console.warn(`Research failed for query "${query}": ${error.message}`);
    return {
      query,
      results: [],
      error: error.message,
      fallback: true
    };
  }
}

Best Practices

1. Always check Context7 availability first - More accurate results
2. Include year in WebSearch queries - Ensure freshness
3. Limit queries to 5-10 - Balance coverage vs speed
4. Synthesize findings - Don't just dump raw results
5. Cache research results - Avoid redundant queries
6. Provide references - Link to source material
7. Time-box research - Don't spend hours researching

References

• Context7 MCP Documentation
• Claude Code WebSearch API
• Research methodology best practices