research-synthesis

Research best practices and synthesize into design decisions for artifact creation. Invoke BEFORE any creator skill to ensure research-backed decisions.

Zur Installation springen

Repository: oimiragieo/agent-studio
Letzte Quellaktivität: 21. April 2026 um 23:45
Erkannte Sprache von SKILL.md: Englisch
Sterne: 36
Forks: 6

Installationsoptionen

Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.

Quelldateien prüfen

Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.

Zurück zur Suche Zurück zur Installation

name	research-synthesis
description	Research best practices and synthesize into design decisions for artifact creation. Invoke BEFORE any creator skill to ensure research-backed decisions.
version	1.2.0
model	sonnet
invoked_by	both
user_invocable	true
tools	["mcp__Exa__web_search_exa","mcp__Exa__get_code_context_exa","WebSearch","WebFetch","Read","Write","Glob","Grep"]
skills	["task-management-protocol"]
triggers	["research for","best practices for","before creating"]
best_practices	["Execute minimum 3 research queries before synthesizing","Consult at least 3 external sources","Document existing codebase patterns","Provide rationale for every design decision","Include risk assessment with mitigations"]
error_handling	graceful
streaming	supported
output_location	.claude/context/artifacts/research-reports/
verified	true
lastVerifiedAt	2026-02-28
source	builtin
trust_score	100
provenance_sha	41e818cfdae02d7a

Research Synthesis Skill

Purpose

Gather and synthesize research BEFORE creating any new artifact (agent, skill, workflow, hook, schema, template). This skill ensures all design decisions are backed by:

Current best practices from authoritative sources
Implementation patterns from real-world examples
Existing codebase conventions to maintain consistency
Risk assessment to anticipate problems

When to Invoke This Skill

MANDATORY BEFORE:

agent-creator - Research agent patterns and domain expertise
skill-creator - Research skill implementation best practices
workflow-creator - Research orchestration patterns
hook-creator - Research validation and safety patterns
schema-creator - Research JSON Schema patterns
template-creator - Research code scaffolding patterns

RECOMMENDED FOR:

New feature design
Architecture decisions
Technology selection
Integration planning

The Iron Law

NO ARTIFACT CREATION WITHOUT RESEARCH FIRST

If you haven't executed the research protocol, you cannot proceed with artifact creation.

Multi-Source Conflict Detection (Inspired by Skill_Seekers unified_scraper)

When synthesizing from 2+ sources, actively detect and flag contradictions. This prevents silent adoption of conflicting advice.

Conflict types to detect:

Conflict Type	Example	Resolution Strategy
Version mismatch	Source A says "use v2 API", Source B says "v3 is required"	Flag with dates, prefer most recent
Contradictory advice	Source A says "always use ORM", Source B says "raw SQL for performance"	Flag both with context, let decision-maker choose
Deprecated patterns	Source A recommends pattern that Source B marks deprecated	Flag with deprecation notice, prefer Source B
Incompatible implementations	Source A uses callbacks, Source B uses async/await

### Conflicts Detected (2)

1. **Version requirement** — React Router docs (2026-03) say v7 required for data loading; Stack Overflow answer (2025-11) assumes v6. **Resolution:** Use v7 (docs are authoritative and more recent).

2. **State management approach** — Official docs recommend Context API for simple state; community blog recommends Zustand universally. **Resolution:** Flag for architect — depends on app complexity.

3-5 QUERIES MAXIMUM PER RESEARCH TASK

10 KB MAXIMUM PER RESEARCH REPORT

// Sub-step 0a: Query internal RAG for cached research on the topic
const { searchInternalContext } = require('.claude/lib/memory/internal-rag.cjs');
const internalResults = await searchInternalContext(researchTopic, { limit: 5, threshold: 0.6 });
const avgSimilarity =
  internalResults.results.length > 0
    ? internalResults.results.reduce((sum, r) => sum + (r.similarity || 0), 0) /
      internalResults.results.length
    : 0;
if (internalResults.results.length >= 3 && avgSimilarity > 0.7) {
  // High-confidence internal hit — synthesize from internal results and skip external search
  console.log(
    '[research-synthesis] Internal RAG hit (avg similarity:',
    avgSimilarity.toFixed(2),
    ') — skipping external search'
  );
}
// Otherwise proceed to external queries below

// Sub-step 0b: Context pressure check
const { checkContextPressure } = require('.claude/lib/utils/context-pressure.cjs');

// Option A — token-budget-based (if budget info available)
const pressure = checkContextPressure({
  tokenBudgetPercent: currentTokenBudgetPercent,
});

// Option B — text-based estimate (when budget % not available)
// const pressure = checkContextPressure({ text: recentContextSnapshot });

if (pressure.pressure === 'high') {
  // STOP — compress context before researching
  console.warn('[research-synthesis] High context pressure:', pressure.reason);
  console.warn('Run context-compressor skill first, then re-invoke research-synthesis.');
  // Return early without executing research queries
  process.exit(0);
}

if (pressure.pressure === 'medium') {
  // Proceed but limit to 3 queries (simple budget)
  console.warn('[research-synthesis] Medium context pressure:', pressure.reason);
  console.warn('Limiting to 3 queries. Consider compressing after research.');
}
// Low pressure → proceed normally with full query budget

## Research Scope Definition

**Artifact Type**: [agent | skill | workflow | hook | schema | template]
**Domain/Capability**: [What this artifact will do]

**Complexity Assessment**:

- [ ] Simple (fact-checking, version checking) → 3 queries
- [ ] Medium (feature comparison, implementation patterns) → 4 queries
- [ ] Complex (comprehensive best practices, ecosystem overview) → 5 queries

**Planned Queries** (list 3-5 BEFORE executing):

1. [Query 1: Best practices - specific question]
2. [Query 2: Implementation patterns - specific question]
3. [Query 3: Framework/AI-specific - specific question]
4. [Optional Query 4: Security/performance - specific question]
5. [Optional Query 5: Trade-offs/alternatives - specific question]

**Key Questions**:

1. What are the best practices for this domain?
2. What implementation patterns exist?
3. What tools/frameworks should be used?
4. What are the common pitfalls?

**Existing Patterns to Examine**:

- .claude/[category]/ - Similar artifacts
- .claude/templates/ - Relevant templates
- .claude/schemas/ - Validation patterns

[ ] Complexity assessed (3, 4, or 5 queries planned)
[ ] Queries planned BEFORE executing (prevents scope creep)
[ ] Each query is specific (not "research everything about X")
[ ] Report size target set (<10 KB)
[ ] Multi-phase split considered (if >5 queries needed)

// Using Exa (preferred for technical content)
mcp__Exa__web_search_exa({
  query: '{artifact_type} {domain} best practices 2024 2025',
  numResults: 5,
});

// Or using WebSearch (fallback)
WebSearch({
  query: '{domain} best practices implementation guide',
});

// Code-focused search
mcp__Exa__get_code_context_exa({
  query: '{domain} implementation patterns examples github',
  tokensNum: 5000,
});

// Or fetch from authoritative sources
WebFetch({
  url: 'https://[authoritative-source]/docs/{topic}',
});

// Framework-specific patterns
mcp__Exa__web_search_exa({
  query: 'Claude AI agent {domain} {artifact_type} patterns',
  numResults: 5,
});

// Or search for MCP patterns
WebSearch({
  query: 'Model Context Protocol {domain} integration',
});

// Find similar artifacts
Glob({ pattern: '.claude/{artifact_category}/**/*.md' });

// Search for related implementations
Grep({ pattern: '{related_keyword}', path: '.claude/' });

// Read existing examples
Read({ file_path: '.claude/{category}/{similar_artifact}' });

[AGENT] User requests: "Create a Slack notification skill"

[AGENT] Step 1: Research first
Skill({ skill: "research-synthesis" })

[RESEARCH-SYNTHESIS] Executing research protocol...
- Query 1: "Slack API best practices 2025"
- Query 2: "Slack MCP server integration patterns"
- Query 3: "Claude AI Slack notification skill"
- Analyzing: .claude/skills/*/SKILL.md for patterns
- Output: Research Report saved

[AGENT] Step 2: Create with research backing
Skill({ skill: "skill-creator" })

[SKILL-CREATOR] Using research report...
- Following design decisions from report
- Applying identified best practices
- Mitigating documented risks

## Research Handoff to: {creator_skill}

**Report Location**: `.claude/context/artifacts/research-reports/{artifact_name}-research.md`

**Summary**:
{2-3 sentence summary of key findings}

**Critical Decisions**:

1. {decision_1}
2. {decision_2}
3. {decision_3}

**Proceed with creation**: YES/NO
**Confidence Level**: High/Medium/Low

Session 1: Research "Rust async/await" (Phase 1: 2 queries)
Session 2: Research "Tokio patterns" (Phase 2: 2 queries)
Session 3: Research "async-trait vs manual impl" (Phase 3: 1 query)

Query: "Rust async/await best practices 2026"
Report structure:
- Definition (100 words)
- Pattern 1: Tokio (200 words)
- Pattern 2: async-trait (150 words)
- Gotchas (100 words)
- Links (10 sources)
---Total: ~550 words, ~3 KB

Query: "everything about Rust ecosystem 2026"
Report: 50 sources, 15 KB (truncated by context limit)
---Can't use findings without context loss

Phase 1 Report: Rust async fundamentals (3 KB)
Phase 2 Report: Tokio implementation patterns (4 KB)
Phase 3 Report: Performance comparison (2 KB)
---Total: 9 KB across 3 sessions (all usable)

Single Report: Comprehensive Rust async guide (25 KB)
---Truncated to 10 KB, missing critical sections

[ ] 3-5 research queries executed (NO MORE THAN 5)
[ ] At least 3 external sources consulted (URLs or authoritative names)
[ ] Existing codebase patterns documented (at least 2 similar artifacts)
[ ] ALL design decisions have rationale AND source
[ ] Risk assessment completed (at least 3 risks with mitigations)
[ ] Recommended implementation path documented
[ ] Report saved to output location
[ ] Report size <10 KB (check file size before saving)

// Step 1: Define scope
// Artifact: skill, Domain: Slack notifications

// Step 2: Execute queries
mcp__Exa__web_search_exa({
  query: 'Slack API webhook best practices 2025',
  numResults: 5,
});

mcp__Exa__get_code_context_exa({
  query: 'Slack notification system implementation Node.js',
  tokensNum: 5000,
});

WebSearch({
  query: 'Claude AI MCP Slack server integration',
});

// Step 3: Analyze codebase
Glob({ pattern: '.claude/skills/*notification*/SKILL.md' });
Glob({ pattern: '.claude/skills/*slack*/SKILL.md' });
Read({ file_path: '.claude/skills/skill-creator/SKILL.md' });

// Step 4: Synthesize and output report
Write({
  file_path: '.claude/context/artifacts/research-reports/slack-notifications-research.md',
  content: '## Research Report: Slack Notifications Skill...',
});

// Research queries for database-architect agent
mcp__Exa__web_search_exa({
  query: 'database design architecture best practices 2025',
  numResults: 5,
});

WebFetch({
  url: 'https://docs.postgresql.org/current/ddl.html',
});

mcp__Exa__web_search_exa({
  query: 'AI agent database schema design automation',
  numResults: 5,
});

// Analyze existing agents
Glob({ pattern: '.claude/agents/domain/*data*.md' });
Read({ file_path: '.claude/agents/core/developer.md' });

Domain	Key Queries	Authoritative Sources
API Integration	"REST API design", "GraphQL patterns"	OpenAPI spec, GraphQL spec
Security	"OWASP top 10", "security best practices"	OWASP, NIST
Database	"database design patterns", "SQL optimization"	PostgreSQL docs, MySQL docs
Frontend	"React patterns", "accessibility WCAG"	React docs, W3C
DevOps	"CI/CD best practices", "IaC patterns"	GitLab docs, Terraform docs
Testing	"TDD patterns", "test automation"	Testing Library, Jest docs
AI/ML	"LLM integration patterns", "prompt engineering"	Anthropic docs, OpenAI docs

cat .claude/context/memory/learnings.md

Creator	Research Focus
`agent-creator`	Domain expertise, agent patterns, skill dependencies
`skill-creator`	Tool integration, MCP patterns, validation hooks
`workflow-creator`	Orchestration patterns, multi-agent coordination
`hook-creator`	Validation patterns, security checks, safety gates
`schema-creator`	JSON Schema patterns, validation strategies
`template-creator`	Code scaffolding, project structure patterns

Anti-Pattern	Why It Fails	Correct Approach
Starting artifact creation before running research protocol	Produces uninformed decisions that conflict with existing patterns and require rework	Always invoke research-synthesis and pass the quality gate before calling any creator skill
Executing 10+ queries to "be thorough"	Causes memory exhaustion and context overflow; later findings are silently lost	Plan exactly 3–5 targeted queries before starting; split complex topics into separate research phases
Writing exhaustive research reports exceeding 10 KB	Oversized reports truncate in the context window, hiding sections the creator skill most needs	Use bullet points, reference URLs instead of copying content, and summarize each source in under 3 sentences
Synthesizing external findings without examining existing codebase	External best practices may conflict with established project patterns and naming conventions	Always glob and read at least 2 similar existing artifacts before writing design decisions
Recording design decisions without source citations	Undocumented decisions cannot be validated, challenged, or traced during future refactoring cycles	Every decision row in the Design Decisions table must include a source URL or authoritative reference name