Researching External Sources

Guide for comprehensive multi-source research that synthesizes findings from documentation, academic papers, and practitioner articles into actionable recommendations.

Instructions

Step 1: Parse Research Parameters

Extract from the request:

• •Topic: Main subject to investigate
• •Date Range (optional): Prioritize recent sources if specified
• •Source Preferences: Any specific sources to focus on

Step 2: Research in Parallel (Conceptually)

Investigate three source categories:

Documentation Sources

• •Official SDK docs (Claude Code, Google ADK, OpenAI)
• •API references and guides
• •Extract: Key concepts, APIs, patterns, best practices
• •Format findings with source URLs

Academic Papers

• •arxiv.org, Google Scholar, ACL Anthology
• •Prioritize last 12 months unless specified
• •Extract: Methodologies, findings, evaluation metrics
• •Include paper URLs and publication dates

Practitioner Articles

• •Engineering blogs, known practitioners
• •Simon Willison, Eugene Yan, vendor blogs
• •Extract: Production experiences, lessons learned
• •Include article URLs and dates

Step 3: Synthesize Cross-Source Findings

Consensus Patterns (High Confidence)

• •Insights appearing across multiple source types
• •Universal best practices
• •Evidence from docs + papers + practice

Unique Insights (Source-Specific Value)

• •Documentation: Technical details, API specs
• •Academic: Novel methodologies, rigorous evaluations
• •Practitioner: Production war stories, real-world constraints

Contradictions & Trade-offs

• •Where sources disagree (note context differences)
• •Evolution of thinking over time
• •Theory vs practice gaps

Step 4: Perform Gap Analysis

Map findings against existing book content:

1. •

   Find related content

   code

   Glob: chapters/**/*.md
   Grep: {topic keywords}
   

2. •

   Assess current coverage

   • •Read identified files
   • •Check frontmatter status
   • •Note partial vs complete coverage
3. •

   Identify gaps

   • •Topics missing from book
   • •Entries needing updates
   • •Areas where research provides deeper insights
   • •Contradictions to existing content (needs correction)

Step 5: Generate Recommendations

Priority 1: Critical Updates

• •Contradicts existing content
• •Fills major foundational gap
• •Supported by all source types
• •High impact

Priority 2: Valuable Additions

• •Extends existing content
• •Supported by 2+ source types
• •Medium-high impact

Priority 3: Nice to Have

• •Interesting but not essential
• •Single-source insights
• •Could seed new questions

For each recommendation:

• •File: Absolute path to target
• •Action: extend | new section | new entry | create questions
• •Insight: Phrased in book voice
• •Sources: Citation numbers
• •Reasoning: Why this priority

Step 6: Save Research Report

Save to: .claude/.cache/research/external/{topic-slug}-{YYYY-MM-DD}.md

Include:

• •Research summary (2-3 sentences)
• •Findings by source type
• •Cross-source synthesis
• •Gap analysis table
• •Priority-ranked recommendations
• •All citations with URLs

Step 7: Report Results

## Research Complete

**Topic:** {topic}
**Date:** {YYYY-MM-DD}

### Sources Researched

| Type | Status | Findings |
|------|--------|----------|
| Documentation | Complete | {count} |
| Academic Papers | Complete | {count} |
| Practitioner Articles | Complete | {count} |

### Cross-Source Synthesis

- **Consensus Patterns:** {count}
- **Unique Insights:** {count}
- **Contradictions:** {count}

### Gap Analysis

- **Existing Coverage:** {count} sections
- **Gaps Found:** {count}

### Top Recommendations

**Priority 1:**
1. `{path}` - {action}: "{insight}"

**Priority 2:**
1. `{path}` - {action}: "{insight}"

### Full Report

Saved to: {report_path}

Key Principles

Cross-Source Validation

• •Consensus across multiple sources = high confidence
• •Single source = interesting but needs validation
• •Documentation + papers + practice = strongest signal

Priority Assignment Logic

• •Contradicts book = always Priority 1 (accuracy matters)
• •Fills foundational gap + multi-source = Priority 1
• •Extends existing + multi-source = Priority 2
• •Single source + novel = Priority 3

Book Voice Integration

• •Phrase insights as learnings, not facts
• •Include production context when available
• •Match existing chapter tone

Citation Management

• •Number all citations sequentially
• •Include full URLs (stable, not temporary)
• •Note source type and publication date
• •Enable verification and deep dives

Examples

Example 1: Research prompt caching

Topic: "prompt caching strategies"

Documentation: Anthropic docs on prompt caching API
Papers: Recent arxiv on KV cache optimization
Articles: Simon Willison on practical caching

Synthesis:
- Consensus: Caching prefix significantly reduces latency
- Unique: Papers show 40% cost reduction metrics
- Trade-off: Memory vs compute at different scales

Gap Analysis:
- chapters/4-context/ mentions caching briefly
- No detailed implementation guidance

Priority 1: Extend 4-context/2-context-strategies.md with caching patterns

Example 2: Research agent orchestration

Topic: "multi-agent coordination patterns"

Sources found across all three types
Strong consensus on supervisor patterns
Contradictions on when to use hierarchical vs flat

Gap Analysis:
- chapters/6-patterns/ has orchestrator chapter
- Missing: comparison of coordination approaches

Priority 1: Add coordination comparison to 6-patterns/3-orchestrator-pattern.md
Priority 2: New section on failure handling

Example 3: No contradictions found

Topic: "tool use best practices"

All sources align on core principles
Practitioner articles add production nuances

Gap Analysis:
- chapters/5-tool-use/ covers basics well
- Could deepen with production examples

Priority 2: Extend with practitioner war stories
Priority 3: Add edge case handling section

Example 4: Partial source failure

Topic: "emerging evaluation methods"

Documentation: Complete
Papers: Complete
Articles: Failed (connection issue)

Report continues with available sources
Note limitation in findings
Suggest manual article search for completeness