researching-external-sources

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

   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