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:

1. Current best practices from authoritative sources
2. Implementation patterns from real-world examples
3. Existing codebase conventions to maintain consistency
4. 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.

Query Limits (IRON LAW)

3-5 QUERIES MAXIMUM PER RESEARCH TASK

Exceeding this limit causes:

• Memory exhaustion (reports >10 KB → context window overflow)
• Information overload (can’t process 10+ sources effectively)
• Diminishing returns (quality > quantity)

Query Budget by Complexity:

• Simple research (fact-checking, version checking): 3 queries
• Medium research (feature comparison, implementation patterns): 4 queries
• Complex research (comprehensive best practices, ecosystem overview): 5 queries

NEVER:

• Execute >5 queries in a single research session
• Execute unbounded “research everything” queries
• Combine multiple unrelated research topics in one session

Multi-Phase Pattern: If research requires >5 queries, split into multiple research sessions (see “Multi-Phase Research Pattern” below).

Report Size Limit (IRON LAW)

10 KB MAXIMUM PER RESEARCH REPORT

Why 10 KB?

• Context efficiency (10 KB = ~2500 words = readable in one context window)
• Forces prioritization (include only essential findings)
• Prevents “encyclopedia syndrome” (copying entire articles)

Format Requirements:

• Use bullet points (compact)
• Reference URLs instead of copying content
• Summarize findings in <3 sentences per source
• Remove noise, keep essentials

When approaching 10 KB:

1. Stop adding new sources
2. Consolidate duplicates
3. Remove redundant details
4. Focus on unique insights

For complex topics:

• Split into 2-3 mini-reports (each <10 KB)
• Each focused on one aspect
• Link reports together in summary

MANDATORY Research Protocol

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',
});

Query 2: Implementation Patterns

// 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}',
});

Query 3: Claude/AI Agent Specific

// 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',
});

Query Efficiency Tips:

• Prefer 2-3 high-quality queries over 10 generic ones
• Combine related questions in one query (“X best practices + implementation patterns”)
• Use WebFetch for known authoritative sources (faster, more focused)
• Stop when you have enough unique insights (quality > quantity)

Step 3: Analyze Existing Codebase

Before synthesizing, examine existing patterns in the codebase:

// 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}' });

What to Extract:

1. Naming conventions – How are similar artifacts named?
2. Structure patterns – What sections do they include?
3. Tool usage – What tools do similar artifacts use?
4. Skill dependencies – What skills are commonly assigned?
5. Output locations – Where do artifacts save their outputs?

Step 4: Synthesize Findings

Output a structured research report in the following format:

## Research Report: {Artifact Name}

**Date**: {YYYY-MM-DD}
**Researcher**: research-synthesis skill
**Artifact Type**: {type}
**Domain**: {domain}

---

### Research Queries Executed

| #   | Query       | Tool      | Sources Found | Key Finding     |
| --- | ----------- | --------- | ------------- | --------------- |
| 1   | "{query_1}" | Exa       | 5             | {brief_finding} |
| 2   | "{query_2}" | WebSearch | 3             | {brief_finding} |
| 3   | "{query_3}" | Exa Code  | 4             | {brief_finding} |

---

### Existing Codebase Patterns

**Similar Artifacts Found:**

- `{path_1}` - {what it does, what patterns it uses}
- `{path_2}` - {what it does, what patterns it uses}

**Conventions Identified:**

- Naming: {convention}
- Structure: {convention}
- Tools: {convention}
- Output: {convention}

---

### Best Practices Identified

| #   | Practice   | Source               | Confidence | Rationale        |
| --- | ---------- | -------------------- | ---------- | ---------------- |
| 1   | {practice} | {source_url_or_name} | High       | {why_applicable} |
| 2   | {practice} | {source_url_or_name} | Medium     | {why_applicable} |
| 3   | {practice} | {source_url_or_name} | High       | {why_applicable} |

**Confidence Levels:**

- **High**: Multiple authoritative sources agree
- **Medium**: Single authoritative source or multiple secondary sources
- **Low**: Limited evidence, requires validation

---

### Design Decisions

| Decision     | Rationale | Source   | Alternatives Considered    |
| ------------ | --------- | -------- | -------------------------- |
| {decision_1} | {why}     | {source} | {what_else_was_considered} |
| {decision_2} | {why}     | {source} | {what_else_was_considered} |
| {decision_3} | {why}     | {source} | {what_else_was_considered} |

---

### Recommended Implementation

**File Location**: `.claude/{category}/{name}/`

**Template to Use**: `.claude/templates/{template}.md`

**Skills to Invoke**:

- `{skill_1}` - {why}
- `{skill_2}` - {why}

**Hooks Needed**:

- `{hook_type}` - {purpose}

**Dependencies**:

- Existing artifacts: {list}
- External tools: {list}

---

### Risk Assessment

| Risk     | Likelihood | Impact | Mitigation       |
| -------- | ---------- | ------ | ---------------- |
| {risk_1} | Medium     | High   | {how_to_prevent} |
| {risk_2} | Low        | Medium | {how_to_prevent} |
| {risk_3} | High       | Low    | {how_to_prevent} |

---

### Quality Gate Checklist

Before proceeding to artifact creation, verify:

- [ ] Minimum 3 research queries executed
- [ ] At least 3 external sources consulted
- [ ] Existing codebase patterns documented
- [ ] All design decisions have rationale and source
- [ ] Risk assessment completed with mitigations
- [ ] Recommended implementation path documented

---

### Next Steps

1. **Invoke creator skill**: `Skill({ skill: "{creator_skill}" })`
2. **Use this report as input**: Reference decisions above
3. **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)

Memory-Aware Chunking Examples

GOOD – Focused query + chunked report:

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

BAD – Unbounded research:

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

GOOD – Phased approach:

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)

BAD – Single massive report:

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/
• Temporary notes: .claude/context/tmp/research/
• Memory updates: .claude/context/memory/learnings.md

Examples

Example 1: Research Before Creating Slack Skill

// 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...',
});

Example 2: Research Before Creating Database Agent

// 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' });

Common Research Domains

File Placement & Standards

Output Location Rules

This skill outputs to: .claude/context/artifacts/research-reports/

Mandatory References

• File Placement: See .claude/docs/FILE_PLACEMENT_RULES.md
• Developer Workflow: See .claude/docs/DEVELOPER_WORKFLOW.md
• Artifact Naming: See .claude/docs/ARTIFACT_NAMING.md

Enforcement

File placement is enforced by file-placement-guard.cjs hook. Invalid placements will be blocked in production mode.

Memory Protocol (MANDATORY)

Before starting:

cat .claude/context/memory/learnings.md

Check for:

• Previous research on similar domains
• Known patterns and conventions
• Documented decisions

After completing:

• New research findings -> Append to .claude/context/memory/learnings.md
• Important decisions -> Append to .claude/context/memory/decisions.md
• Issues found -> Append to .claude/context/memory/issues.md

ASSUME INTERRUPTION: Your context may reset. If it’s not in memory, it didn’t happen.

Workflow Integration

This skill integrates with the Creator Ecosystem:

Full lifecycle: .claude/workflows/core/skill-lifecycle.md

Iron Laws of Research Synthesis

1. NO CREATION WITHOUT RESEARCH FIRST
   - Skip research = uninformed decisions = bugs and rework
   - Research ALWAYS precedes creation

2. NO MORE THAN 5 QUERIES PER RESEARCH SESSION
   - Execute exactly 3-5 queries (no more)
   - >5 queries = memory exhaustion, context loss
   - If need more → split into multi-phase research

3. NO RESEARCH REPORTS >10 KB
   - Maximum 10 KB per report (~2500 words)
   - Exceeding limit → context window overflow
   - Use bullet points, reference URLs, summarize findings

4. NO SYNTHESIS WITHOUT CODEBASE ANALYSIS
   - External research is necessary but not sufficient
   - MUST examine existing patterns for consistency

5. NO DECISIONS WITHOUT RATIONALE
   - Every decision needs a source
   - "I think" is not a source. Link to evidence.

6. NO PROCEEDING WITHOUT QUALITY GATE
   - All checklist items must pass (including query/size limits)
   - BLOCKING: Incomplete research = no creation