Research Patterns

Research Patterns Skill

Purpose: Provide methodology and guidelines for researching existing patterns before implementing new features.

Auto-activates when: Keywords like "research", "investigate", "design", "architecture", "best practice" appear in conversation.

Research Methodology

1. Define Clear Research Question

Before starting research:

❓ **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?}

Example:

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

2. Search Existing Codebase First

Always search internal patterns before external research.

Codebase Search Checklist:

□ 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

Common Search Patterns:

Decision Tree:

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

3. External Web Research

When codebase search yields nothing, research externally.

WebSearch Query Strategy:

Query Pattern Templates

For Best Practices:

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

For Implementation Guidance:

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

For Security-Sensitive Topics:

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

For Performance-Critical Topics:

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

For Architecture Decisions:

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

Optimal Query Count

• Minimum: 3 queries (different angles on same topic)
• Recommended: 5 queries (comprehensive coverage)
• Maximum: 7 queries (diminishing returns after this)

Example Research Plan:

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"

4. Source Quality Evaluation

Not all sources are created equal. Prioritize quality over quantity.

Source Hierarchy (Highest to Lowest)

Recency Scoring

Exceptions (where older sources are acceptable):

• Fundamental algorithms (sorting, graphs, etc.)
• Established design patterns (Gang of Four patterns)
• Mathematical foundations
• Core Python language features (pre-3.11)

Content Quality Scoring

Award points for:

• ✅ Multiple code examples (+2)
• ✅ Pros and cons comparison (+2)
• ✅ Performance benchmarks (+1)
• ✅ Security considerations (+1)
• ✅ Edge cases documented (+1)
• ✅ Testing examples (+1)
• ✅ Production experience shared (+1)

Deduct points for:

• ❌ Theory only, no code (-2)
• ❌ Incomplete examples (-1)
• ❌ No error handling shown (-1)
• ❌ Conflicting advice (-1)
• ❌ Obvious mistakes in code (-2)

Overall Quality Formula:

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

5. Distill Into Actionable Findings

Transform research into implementation-ready guidance.

Required Sections in Findings

1. Executive Summary (2-3 sentences)

• What's the recommended approach?
• Why is it best for our use case?
• What's the expected effort?

2. Pattern Analysis

• Recommended Approach: Detailed description + code example
• Alternatives Considered: At least 2 alternatives with pros/cons
• Tradeoffs: Comparison table

3. Implementation Guide

• Step-by-Step: Numbered steps with code examples
• Integration Points: Where in our codebase this fits
• Dependencies: Libraries, tools, infrastructure needed

4. Pitfalls to Avoid

• Common Mistakes: What developers often get wrong
• Edge Cases: Scenarios that need special handling
• Security Considerations: Vulnerabilities to prevent
• Performance Issues: Bottlenecks to avoid

5. Source Evaluation

• Table of all sources with quality ratings
• Notes on why each source was useful/not useful

6. Next Steps

• Recommended actions
• Files to create/modify
• Tests to write

Pattern Recognition Framework

Common Software Patterns

1. Authentication/Authorization

Research Focus:

• OAuth 2.0 vs JWT vs API keys
• Session management
• Token refresh strategies
• RBAC vs ABAC

Key Questions:

• How are credentials stored securely?
• How is token expiration handled?
• What's the logout flow?
• How to handle concurrent sessions?

Security Musts:

• Password hashing (bcrypt, argon2)
• HTTPS only
• CSRF protection
• Rate limiting

2. Caching

Research Focus:

• Cache invalidation strategies
• Cache eviction policies (LRU, LFU, TTL)
• Distributed vs local caching
• Cache coherence

Key Questions:

• What's the cache hit ratio target?
• How to handle cache misses?
• When to invalidate?
• How to prevent cache stampede?

Common Patterns:

• Write-through cache
• Write-behind cache
• Cache-aside
• Read-through cache

3. Webhooks/Event Processing

Research Focus:

• Signature verification
• Retry logic and exponential backoff
• Idempotency
• Async vs sync processing

Key Questions:

• How to verify webhook authenticity?
• What happens if processing fails?
• How to prevent duplicate processing?
• How to handle order of events?

Security Musts:

• HMAC signature verification
• IP whitelisting (if applicable)
• Request validation
• Rate limiting

4. API Design

Research Focus:

• REST vs GraphQL vs gRPC
• Versioning strategies
• Error response formats
• Pagination approaches

Key Questions:

• How to handle breaking changes?
• What's the rate limiting strategy?
• How to document the API?
• How to test the API?

Best Practices:

• Semantic versioning
• OpenAPI/Swagger docs
• Consistent error formats
• HATEOAS (if REST)

5. Data Processing Pipelines

Research Focus:

• ETL vs ELT
• Batch vs stream processing
• Error handling and retries
• Monitoring and alerting

Key Questions:

• How to handle partial failures?
• How to ensure data quality?
• How to scale processing?
• How to monitor pipeline health?

Common Tools:

• Apache Airflow (batch)
• Apache Kafka (streaming)
• dbt (data transformation)
• Prefect (orchestration)

6. Testing Strategies

Research Focus:

• Unit vs integration vs E2E tests
• Test data management
• Mocking strategies
• Coverage targets

Key Questions:

• What's the right test pyramid?
• How to test external dependencies?
• How to test async code?
• How to ensure tests are fast?

Best Practices:

• Arrange-Act-Assert pattern
• Given-When-Then (BDD)
• Test isolation
• Fast feedback loops

Research Output Templates

Template 1: Pattern Comparison

Use when comparing multiple approaches (e.g., "Redis vs Memcached"):

# 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
```

Option B

# Example implementation

Option C

# Example implementation

Decision Matrix

For our use case (insert our specific requirements):

Winner: {Option} because {reasoning}

### 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

[Simple ASCII diagram or description] Component A → Component B → Component C

## Step-by-Step Implementation

### Step 1: {First step name}

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

```python
# Code for step 1

Testing:

# Test for step 1

Step 2: {Second step name}

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

# Code for step 2

Testing:

# Test for step 2

[Continue for all steps...]

Integration Example

How it fits into our codebase:

# Example showing integration with existing code

Configuration

Environment variables:

FEATURE_API_KEY=xxx
FEATURE_TIMEOUT=30

Config file (config.yaml):

feature:
  enabled: true
  timeout: 30
  retry_attempts: 3

Error Handling

Common errors and solutions:

1. Error: {Error description}

   • Cause: {Why it happens}
   • Solution: {How to fix}
   • Prevention: {How to avoid}

2. Error: {Error description}

   • Cause: {Why it happens}
   • Solution: {How to fix}
   • Prevention: {How to avoid}

Monitoring

Metrics to track:

• {Metric 1}: {Description + target value}
• {Metric 2}: {Description + target value}
• {Metric 3}: {Description + target value}

Alerts to set up:

• {Alert 1}: {Trigger condition}
• {Alert 2}: {Trigger condition}

Testing Strategy

Unit tests:

• Test {functionality A}
• Test {functionality B}

Integration tests:

• Test {workflow A}
• Test {workflow B}

Security tests:

• Test {attack vector A}
• Test {attack vector B}

### 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

❌ Insecure:

# Example of what NOT to do

Compliance Requirements

Applicable standards:

• GDPR: {Relevant requirements}
• OWASP: {Relevant guidelines}
• SOC 2: {Relevant controls}

Penetration Testing Plan

Tests to run:

1. {Test name}: {What to test}
2. {Test name}: {What to test}
3. {Test name}: {What to test}

---

## 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

User request: "Design a webhook system" ↓ auto_research_trigger.py detects design question ↓ researcher subagent auto-invokes ↓ research-patterns skill provides methodology (THIS SKILL) ↓ researcher performs:

1. Codebase search
2. WebSearch (5 queries)
3. WebFetch (5+ sources)
4. Analysis & distillation
5. Save findings to docs/research/
6. Stage changes ↓ researcher reports: "Research complete, see docs/research/20251018_webhook_system/findings.md" ↓ planner subagent uses findings to create implementation plan ↓ tester subagent writes tests based on findings ↓ implementer subagent implements following findings ↓ Feature complete, aligned with best practices ✅

### 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.**