❓ **Research Question Template**:

- What: {What are we trying to build?}
- Why: {Why do we need it?}
- Scope: {What's in scope? What's out of scope?}
- Success: {What would a good solution look like?}

What: Webhook handling system for receiving external events
Why: Need to integrate with 3rd-party services that push updates
Scope: IN - signature verification, retry logic, async processing
OUT - webhook delivery (we're receiving, not sending)
Success: Secure, reliable, handles 1000+ webhooks/min

□ Grep for relevant keywords (functionality, domain terms)
□ Glob for related files (naming patterns)
□ Read existing implementations (understand current patterns)
□ Check docs/ for existing architecture decisions
□ Review tests/ to understand current test patterns

Found existing pattern?
├─ YES → Reuse/extend existing pattern
│         (Don't reinvent the wheel!)
│
└─ NO → Proceed with external research
        (Need to find industry best practices)

"{topic} best practices {current_year}"
"{topic} design patterns {current_year}"
"{topic} common mistakes to avoid"
"{topic} anti-patterns"

"{topic} {language} implementation"
"{topic} code examples GitHub"
"{topic} library comparison"
"{topic} step-by-step tutorial"

"{topic} security best practices"
"{topic} OWASP guidelines"
"{topic} secure implementation"
"{topic} vulnerability checklist"

"{topic} performance optimization"
"{topic} scalability patterns"
"{topic} benchmarking"
"{topic} profiling and tuning"

"{topic} architecture patterns"
"{topic} system design"
"{topic} microservices vs monolith"
"{topic} when to use"

Topic: "distributed caching for ML models"

Query 1: "distributed caching best practices 2025"
Query 2: "distributed caching Python Redis examples"
Query 3: "ML model caching strategies"
Query 4: "caching invalidation patterns"
Query 5: "Redis vs Memcached performance comparison"

Quality = (Authority × 0.3) + (Recency × 0.25) + (Content × 0.2) + (Depth × 0.15) + (Confirmation × 0.1)

# Comparison: {Option A} vs {Option B} vs {Option C}

## Quick Recommendation

**Use {Option A}** if: {scenario}
**Use {Option B}** if: {scenario}
**Use {Option C}** if: {scenario}

## Detailed Comparison

| Criterion       | Option A         | Option B         | Option C         |
| --------------- | ---------------- | ---------------- | ---------------- |
| **Performance** | {rating + notes} | {rating + notes} | {rating + notes} |
| **Complexity**  | {rating + notes} | {rating + notes} | {rating + notes} |
| **Scalability** | {rating + notes} | {rating + notes} | {rating + notes} |
| **Maintenance** | {rating + notes} | {rating + notes} | {rating + notes} |
| **Community**   | {rating + notes} | {rating + notes} | {rating + notes} |
| **Cost**        | {rating + notes} | {rating + notes} | {rating + notes} |

## Code Examples

### Option A

```python
# Example implementation
```

# Example implementation

# Example implementation

### Template 2: Implementation Pattern

Use when researching how to implement a feature (e.g., "webhook handling"):

```markdown
# Implementation Pattern: {Feature Name}

## Pattern Overview

**Name**: {Pattern name}
**Category**: {Architectural pattern category}
**Use When**: {Scenarios where this pattern applies}

## Architecture Diagram

## Step-by-Step Implementation

### Step 1: {First step name}

**What**: {What this step does}
**Why**: {Why it's necessary}

```python
# Code for step 1

# Test for step 1

# Code for step 2

# Test for step 2

# Example showing integration with existing code

FEATURE_API_KEY=xxx
FEATURE_TIMEOUT=30

feature:
  enabled: true
  timeout: 30
  retry_attempts: 3

### Template 3: Security Analysis

Use when researching security-sensitive features:

```markdown
# Security Analysis: {Feature Name}

## Threat Model

### Assets
- {Asset 1}: {Description + value}
- {Asset 2}: {Description + value}

### Threats
1. **{Threat name}** (Severity: High/Medium/Low)
   - Attack vector: {How attack happens}
   - Impact: {What damage occurs}
   - Likelihood: {How likely}

2. **{Threat name}** (Severity: High/Medium/Low)
   - Attack vector: {How attack happens}
   - Impact: {What damage occurs}
   - Likelihood: {How likely}

### Mitigations

| Threat | Mitigation | Implementation | Status |
|--------|------------|----------------|--------|
| {Threat 1} | {How to prevent} | {Code/config} | ✅/❌ |
| {Threat 2} | {How to prevent} | {Code/config} | ✅/❌ |

## OWASP Top 10 Analysis

**Relevant OWASP risks for this feature**:

1. **{OWASP Risk}**: {How it applies}
   - Mitigation: {How we prevent it}

2. **{OWASP Risk}**: {How it applies}
   - Mitigation: {How we prevent it}

## Security Checklist

**Before deployment, verify**:

- [ ] Input validation (all user inputs sanitized)
- [ ] Authentication (only authorized users)
- [ ] Authorization (proper permission checks)
- [ ] Encryption (data at rest + in transit)
- [ ] Logging (security events logged)
- [ ] Rate limiting (prevent abuse)
- [ ] Error handling (no sensitive info leakage)
- [ ] Dependencies (no known vulnerabilities)
- [ ] Secret management (no hardcoded secrets)
- [ ] Security headers (CSP, HSTS, etc.)

## Secure Code Examples

**✅ Secure**:
```python
# Example of secure implementation

# Example of what NOT to do

---

## Research Quality Gates

**Before marking research as complete, verify**:

### Completeness Gates

- [ ] **Research question clearly defined**
- [ ] **Codebase searched first** (Grep + Glob + Read)
- [ ] **External research performed** (3-5 WebSearch queries)
- [ ] **Top sources fetched** (5+ WebFetch calls)
- [ ] **Findings documented** (follows template)
- [ ] **Sources evaluated** (quality ratings assigned)
- [ ] **Next steps provided** (actionable recommendations)

### Quality Gates

- [ ] **Code examples included** (not just theory)
- [ ] **Security considered** (if applicable)
- [ ] **Performance analyzed** (if applicable)
- [ ] **Tradeoffs documented** (pros and cons)
- [ ] **Integration points identified** (where it fits in codebase)
- [ ] **Tests recommended** (what to test)
- [ ] **Sources are recent** (2024-2025 preferred)

### Clarity Gates

- [ ] **Executive summary is clear** (2-3 sentences)
- [ ] **Recommendation is specific** (not vague)
- [ ] **Implementation steps are detailed** (can follow without questions)
- [ ] **Pitfalls are concrete** (specific mistakes to avoid)
- [ ] **Next steps are actionable** (can start immediately)

**If any gate fails, research is NOT complete.**

---

## Common Research Anti-Patterns

### ❌ Anti-Pattern 1: Skipping Codebase Search

**Problem**: Researching external patterns without checking if we already have a solution.

**Why Bad**: Reinventing the wheel, inconsistent patterns, wasted time.

**Solution**: ALWAYS search codebase first with Grep + Glob + Read.

### ❌ Anti-Pattern 2: Using Outdated Sources

**Problem**: Relying on tutorials from 2019-2020.

**Why Bad**: Outdated practices, deprecated APIs, security vulnerabilities.

**Solution**: Prioritize 2024-2025 sources. If using older sources, verify they're still current.

### ❌ Anti-Pattern 3: Theory Without Examples

**Problem**: Findings describe patterns but don't show code.

**Why Bad**: Implementer can't translate theory to code without guessing.

**Solution**: Always include multiple code examples with context.

### ❌ Anti-Pattern 4: No Tradeoff Analysis

**Problem**: Recommending one approach without explaining alternatives.

**Why Bad**: Reader doesn't understand WHY this is best for our use case.

**Solution**: Compare at least 2-3 alternatives with pros/cons table.

### ❌ Anti-Pattern 5: Ignoring Security

**Problem**: Researching implementation without security considerations.

**Why Bad**: Vulnerable code gets deployed, security issues discovered later.

**Solution**: Always include security section, even if just "N/A - not security-sensitive".

### ❌ Anti-Pattern 6: Vague Next Steps

**Problem**: "Research complete, proceed with implementation" without specific actions.

**Why Bad**: Implementer doesn't know what files to create or what to do first.

**Solution**: Provide specific, numbered next steps with file names.

---

## Integration with Autonomous Architecture

### How Research Fits Into Workflow

### Research Feeds Other Subagents

**planner** uses research findings to:
- Choose architectural patterns
- Design system components
- Plan implementation phases

**tester** uses research findings to:
- Identify edge cases to test
- Write security tests
- Create performance benchmarks

**implementer** uses research findings to:
- Follow recommended patterns
- Avoid documented pitfalls
- Use proven code examples

**security-auditor** uses research findings to:
- Check for documented vulnerabilities
- Verify security best practices followed
- Validate against OWASP guidelines

**doc-syncer** uses research findings to:
- Document architectural decisions
- Link to research sources
- Explain pattern choices

---

## Example Research Workflows

### Workflow 1: Architecture Decision

**Trigger**: "Should we use microservices or monolith for this feature?"

**Research Process**:
1. Define question: "What architecture pattern for feature X with Y requirements?"
2. Codebase search: Check existing architecture (`docs/architecture/`)
3. WebSearch:
   - "microservices vs monolith decision criteria 2025"
   - "when to use microservices"
   - "monolith to microservices migration patterns"
4. WebFetch: Martin Fowler, microservices.io, AWS architecture blog
5. Distill findings:
   - Comparison table (complexity, ops, scaling, etc.)
   - Decision tree based on our requirements
   - Recommendation with clear reasoning

**Output**: `docs/research/20251018_architecture_decision/findings.md`

### Workflow 2: Library Comparison

**Trigger**: "Which Python caching library should we use?"

**Research Process**:
1. Define question: "Best caching library for ML model inference with TTL support?"
2. Codebase search: Check if we already use a caching library
3. WebSearch:
   - "Python caching libraries comparison 2025"
   - "Redis vs Memcached Python"
   - "cachetools vs dogpile.cache"
4. WebFetch: Official docs for top 3 libraries, performance benchmarks
5. Distill findings:
   - Feature comparison table
   - Performance benchmarks
   - Ease of use comparison
   - Recommendation based on our needs

**Output**: `docs/research/20251018_caching_library/findings.md`

### Workflow 3: Security Pattern

**Trigger**: "How should we handle API key authentication?"

**Research Process**:
1. Define question: "Secure API key authentication for external API?"
2. Codebase search: Check current auth patterns
3. WebSearch:
   - "API key authentication best practices 2025"
   - "API key security OWASP"
   - "API key vs OAuth comparison"
4. WebFetch: OWASP API Security, Auth0 docs, security blogs
5. Distill findings:
   - Security threat model
   - Recommended implementation (key rotation, rate limiting, etc.)
   - OWASP compliance checklist
   - Secure code examples

**Output**: `docs/research/20251018_api_key_auth/findings.md`

---

## Key Takeaways

1. **Research is an investment**: 20 minutes of research saves hours of refactoring.

2. **Codebase first**: Don't reinvent patterns we already have.

3. **Quality over quantity**: 3 great sources > 10 mediocre sources.

4. **Code examples are mandatory**: Theory alone is not actionable.

5. **Security is non-negotiable**: Always consider security implications.

6. **Tradeoffs must be explicit**: Help decision-makers understand choices.

7. **Recent sources preferred**: 2024-2025 for current best practices.

8. **Research feeds the whole workflow**: Findings guide all downstream subagents.

---

**This skill enables confident, informed implementation by ensuring we learn from the industry before we build.**