Research best practices and synthesize into design decisions for artifact creation. Invoke BEFORE any creator skill to ensure research-backed decisions.
Research best practices and synthesize into design decisions for artifact creation. Invoke BEFORE any creator skill to ensure research-backed decisions.
["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
Flag with migration path if available
Detection protocol:
After collecting findings from all sources, build a claim matrix — extract factual claims from each source
Compare claims pairwise for contradictions using semantic overlap (same topic, different recommendation)
For each conflict, record: { claim_a, source_a, claim_b, source_b, conflictType, suggestedResolution }
Include a conflicts section in the synthesis report — never silently pick one side
Conflict output in report:
### 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.
BEFORE executing any external research queries, first search internal project memory.
If sufficient high-confidence results exist internally, skip external queries entirely.
Then check context pressure before proceeding.
// Sub-step 0a: Query internal RAG for cached research on the topicconst { searchInternalContext } = require('.claude/lib/memory/internal-rag.cjs');
const internalResults = awaitsearchInternalContext(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 searchconsole.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 checkconst { 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 researchingconsole.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
Enforcement:
Pressure
Action
high
STOP — invoke context-compressor skill, then retry
medium
Limit to 3 queries, warn caller
low
Proceed normally with full query budget (3–5 queries)
Step 1: Define Research Scope & Plan Queries
Before executing queries, define scope AND plan 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
Pre-Research Checklist:
[ ] 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)
Step 2: Execute Research Queries (3-5 Maximum)
Execute exactly 3-5 research queries (no more). More queries = memory exhaustion and context loss.
Query 1: Best Practices
// 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',
});
Use this report as input: Reference decisions above
Validate against checklist: Before marking complete
Integration with Creator Skills
Pre-Creation Workflow
[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
Handoff Format
After completing research, provide this handoff to the creator skill:
## 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
Multi-Phase Research Pattern (for complex topics)
When research complexity exceeds 5 queries, split into phases:
Phase 1: Scope & Definition (2 queries)
What is the topic/technology?
What are the key concepts?
Phase 2: Implementation (2 queries)
How do experts implement this?
Common patterns & best practices?
Phase 3: Comparison & Trade-offs (1 query)
How does this compare to alternatives?
Trade-offs & gotchas?
Benefits:
Each phase is independent (less context bleed)
Can be done in separate skill invocations
Clearer organization
Easier to reuse findings
Example:
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)
Single Report: Comprehensive Rust async guide (25 KB)
---Truncated to 10 KB, missing critical sections
Quality Gate
Research is complete when ALL items pass:
[ ] 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)
BLOCKING: If any item fails, research is INCOMPLETE. Do not proceed to artifact creation.
Output Locations
Research reports: .claude/context/artifacts/research-reports/
Full lifecycle:.claude/workflows/core/skill-lifecycle.md
Iron Laws
NEVER create any artifact without completing the research protocol first — uninformed creation produces decisions that conflict with existing patterns and require expensive rework.
NEVER execute more than 5 queries per research session — exceeding the limit causes memory exhaustion and context window overflow where later findings are silently lost.
NEVER produce a research report exceeding 10 KB — oversized reports overflow the context window and force truncation of findings at the most critical sections.
ALWAYS analyze at least 2 existing codebase artifacts before synthesizing external research — external best practices alone miss project-specific conventions and produce inconsistent implementations.
ALWAYS document a source and rationale for every design decision — decisions without evidence cannot be evaluated, challenged, or traced during future refactoring.
Anti-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
