notion-research-documentation

Original source / Raw SKILL.md

---
name: notion-research-documentation
description: Searches across your Notion workspace, synthesizes findings from multiple pages, and creates comprehensive research documentation saved as new Notion pages. Turns scattered information into structured reports with proper citations and actionable insights.
---

# Research & Documentation

Enables comprehensive research workflows: search for information across your Notion workspace, fetch and analyze relevant pages, synthesize findings, and create well-structured documentation.

## Quick Start

When asked to research and document a topic:

1. **Search for relevant content**: Use `Notion:notion-search` to find pages
2. **Fetch detailed information**: Use `Notion:notion-fetch` to read full page content
3. **Synthesize findings**: Analyze and combine information from multiple sources
4. **Create structured output**: Use `Notion:notion-create-pages` to write documentation

## Research Workflow

### Step 1: Search for relevant information

```
Use Notion:notion-search with the research topic
Filter by teamspace if scope is known
Review search results to identify most relevant pages
```

### Step 2: Fetch page content

```
Use Notion:notion-fetch for each relevant page URL
Collect content from all relevant sources
Note key findings, quotes, and data points
```

### Step 3: Synthesize findings

Analyze the collected information:
- Identify key themes and patterns
- Connect related concepts across sources
- Note gaps or conflicting information
- Organize findings logically

### Step 4: Create structured documentation

Use the appropriate documentation template (see [reference/format-selection-guide.md](reference/format-selection-guide.md)) to structure output:
- Clear title and executive summary
- Well-organized sections with headings
- Citations linking back to source pages
- Actionable conclusions or next steps

## Output Formats

Choose the appropriate format based on request:

**Research Summary**: See [reference/research-summary-format.md](reference/research-summary-format.md)
**Comprehensive Report**: See [reference/comprehensive-report-format.md](reference/comprehensive-report-format.md)
**Quick Brief**: See [reference/quick-brief-format.md](reference/quick-brief-format.md)

## Best Practices

1. **Cast a wide net first**: Start with broad searches, then narrow down
2. **Cite sources**: Always link back to source pages using mentions
3. **Verify recency**: Check page last-edited dates for current information
4. **Cross-reference**: Validate findings across multiple sources
5. **Structure clearly**: Use headings, bullets, and formatting for readability

## Page Placement

By default, create research documents as standalone pages. If the user specifies:
- A parent page → use `page_id` parent
- A database → fetch the database first, then use appropriate `data_source_id`
- A teamspace → create in that context

## Advanced Features

**Search filtering**: See [reference/advanced-search.md](reference/advanced-search.md)
**Citation styles**: See [reference/citations.md](reference/citations.md)

## Common Issues

**"No results found"**: Try broader search terms or different teamspaces
**"Too many results"**: Add filters or search within specific pages
**"Can't access page"**: User may lack permissions, ask them to verify access

## Examples

See [examples/](examples/) for complete workflow demonstrations:
- [examples/market-research.md](examples/market-research.md) - Researching market trends
- [examples/technical-investigation.md](examples/technical-investigation.md) - Technical deep-dive
- [examples/competitor-analysis.md](examples/competitor-analysis.md) - Multi-source synthesis



---

## Referenced Files

> The following files are referenced in this skill and included for context.

### reference/format-selection-guide.md

```markdown
# Format Selection Guide

Choose the right output format for your research needs.

## Decision Tree

```
Is this comparing multiple options?
  ├─ YES → Use Comparison Format
  └─ NO ↓

Is this time-sensitive or simple?
  ├─ YES → Use Quick Brief
  └─ NO ↓

Does this require formal/extensive documentation?
  ├─ YES → Use Comprehensive Report
  └─ NO → Use Research Summary (default)
```

## Format Overview

| Format | Length | When to Use | Template |
|--------|--------|-------------|----------|
| [Research Summary](research-summary-format.md) | 500-1000 words | Most research requests (default) | [Template](research-summary-template.md) |
| [Comprehensive Report](comprehensive-report-format.md) | 1500+ words | Formal docs, strategic decisions | [Template](comprehensive-report-template.md) |
| [Quick Brief](quick-brief-format.md) | 200-400 words | Time-sensitive, simple topics | [Template](quick-brief-template.md) |
| [Comparison](comparison-format.md) | 800-1200 words | Evaluating options | [Template](comparison-template.md) |

## Formatting Guidelines

### Headings
- Use `#` for title
- Use `##` for major sections
- Use `###` for subsections
- Keep heading hierarchy consistent

### Lists
- Use `-` for bullet points
- Use `1.` for numbered lists
- Keep list items parallel in structure

### Emphasis
- Use `**bold**` for key terms and section labels
- Use `*italic*` for emphasis
- Use sparingly for maximum impact

### Citations
- Always use `<mention-page url="...">Page Title</mention-page>` for source pages
- Include citation immediately after referenced information
- Group all sources in a "Sources" section at the end

### Tables
- Use for structured data comparison
- Keep columns to 3-5 for readability
- Include header row
- Align content appropriately

### Code Blocks
Use when including:
- Technical specifications
- Configuration examples
- Command examples

```
Example code or configuration here
```

## Content Guidelines

### Executive Summaries
- Lead with the most important finding
- Include 1-2 key implications
- Make it standalone (reader gets value without reading further)
- Target 2-3 sentences for summaries, 1 paragraph for reports

### Key Findings
- Start with a clear headline
- Support with specific evidence
- Include relevant data points or quotes
- Cite source immediately
- Focus on actionable insights

### Recommendations
- Make them specific and actionable
- Explain the "why" behind each recommendation
- Prioritize clearly (Priority 1, 2, 3 or High/Medium/Low)
- Include implementation hints when relevant

### Source Citations
- Link to original pages using mentions
- Note if information is outdated (check last-edited dates)
- Credit specific sections when quoting
- Group related sources together


```

### reference/research-summary-format.md

```markdown
# Research Summary Format

**When to use**: General research requests, most common format

## Characteristics

**Length**: 500-1000 words typically

**Structure**:
- Executive summary (2-3 sentences)
- 3-5 key findings with supporting evidence
- Detailed analysis section
- Conclusions and next steps
- Source citations

## Template

See [research-summary-template.md](research-summary-template.md) for the full template.

## Best For

- Most general-purpose research requests
- Standard documentation needs
- Balanced depth and readability
- When you need comprehensive but accessible information

## Example Use Cases

- "Research our authentication options"
- "What does our project documentation say about the API redesign?"
- "Summarize the team's discussion about mobile strategy"
- "Compile information about our deployment process"


```

### reference/comprehensive-report-format.md

```markdown
# Comprehensive Report Format

**When to use**: 
- Formal documentation requirements
- Strategic decision support
- Complex topics requiring extensive analysis
- Multiple stakeholders need alignment

## Characteristics

**Length**: 1500+ words

**Structure**:
- Executive summary
- Background & context
- Methodology
- Detailed findings with subsections
- Data & evidence section
- Implications (short and long-term)
- Prioritized recommendations
- Appendix

## Template

See [comprehensive-report-template.md](comprehensive-report-template.md) for the full template.

## Best For

- Deep analysis and strategic decisions
- Formal documentation requirements
- Complex topics with multiple facets
- When stakeholders need extensive context
- Board presentations or executive briefings

## Example Use Cases

- "Create a comprehensive analysis of our market position"
- "Document the full technical investigation of the database migration"
- "Prepare an in-depth report on vendor options for executive review"
- "Analyze the pros and cons of different architectural approaches"


```

### reference/quick-brief-format.md

```markdown
# Quick Brief Format

**When to use**:
- Time-sensitive requests
- Simple topics
- Status updates
- Quick reference needs

## Characteristics

**Length**: 200-400 words

**Structure**:
- 3-4 sentence summary
- 3-5 bullet key points
- Short action items list
- Brief source list

## Template

See [quick-brief-template.md](quick-brief-template.md) for the full template.

## Best For

- Fast turnaround requests
- Simple, straightforward topics
- Quick status updates
- When time is more important than depth
- Initial exploration before deeper research

## Example Use Cases

- "Quick summary of what's in our API docs"
- "Fast brief on the meeting notes from yesterday"
- "What are the key points from that spec?"
- "Give me a quick overview of the project status"


```

### reference/advanced-search.md

```markdown
# Advanced Search Techniques

## Search Filtering

### By Date Range

Use `created_date_range` to find recent content:

```
filters: {
  created_date_range: {
    start_date: "2024-01-01",
    end_date: "2025-01-01"
  }
}
```

**When to use**:
- Finding recent updates on a topic
- Focusing on current information
- Excluding outdated content

### By Creator

Use `created_by_user_ids` to find content from specific people:

```
filters: {
  created_by_user_ids: ["user-id-1", "user-id-2"]
}
```

**When to use**:
- Research from subject matter experts
- Team-specific information
- Attribution tracking

### Combined Filters

Stack filters for precision:

```
filters: {
  created_date_range: {
    start_date: "2024-10-01"
  },
  created_by_user_ids: ["expert-user-id"]
}
```

## Scoped Searches

### Teamspace Scoping

Restrict search to specific teamspace:

```
teamspace_id: "teamspace-uuid"
```

**When to use**:
- Project-specific research
- Department-focused information
- Reducing noise from irrelevant results

### Page Scoping

Search within a specific page and its subpages:

```
page_url: "https://notion.so/workspace/Page-Title-uuid"
```

**When to use**:
- Research within a project hierarchy
- Documentation updates
- Focused investigation

### Database Scoping

Search within a database's content:

```
data_source_url: "collection://data-source-uuid"
```

**When to use**:
- Task/project database research
- Structured data investigation
- Finding specific entries

## Search Strategies

### Broad to Narrow

1. Start with general search term
2. Review results for relevant teamspaces/pages
3. Re-search with scope filters
4. Fetch detailed content from top results

**Example**:
```
Search 1: query="API integration" → 50 results across workspace
Search 2: query="API integration", teamspace_id="engineering" → 12 results
Fetch: Top 3-5 most relevant pages
```

### Multi-Query Approach

Run parallel searches with related terms:

```
Query 1: "API integration"
Query 2: "API authentication"
Query 3: "API documentation"
```

Combine results to build comprehensive picture.

### Temporal Research

Search across time periods to track evolution:

```
Search 1: created_date_range 2023 → Historical context
Search 2: created_date_range 2024 → Recent developments
Search 3: created_date_range 2025 → Current state
```

## Result Processing

### Identifying Relevant Results

Look for:
- **High semantic match**: Result summary closely matches query intent
- **Recent updates**: Last-edited date is recent
- **Authoritative sources**: Created by known experts or in official locations
- **Comprehensive content**: Result summary suggests detailed information

### Prioritizing Fetches

Fetch pages in order of relevance:

1. **Primary sources**: Direct documentation, official pages
2. **Recent updates**: Newly edited content
3. **Related context**: Supporting information
4. **Historical reference**: Background and context

Don't fetch everything - be selective based on research needs.

### Handling Too Many Results

If search returns 20+ results:

1. **Add filters**: Narrow by date, creator, or teamspace
2. **Refine query**: Use more specific terms
3. **Use page scoping**: Search within relevant parent page
4. **Sample strategically**: Fetch diverse results (recent, popular, authoritative)

### Handling Too Few Results

If search returns < 3 results:

1. **Broaden query**: Use more general terms
2. **Remove filters**: Search full workspace
3. **Try synonyms**: Alternative terminology
4. **Search in related areas**: Adjacent teamspaces or pages

## Search Quality

### Effective Search Queries

**Good queries** (specific, semantic):
- "Q4 product roadmap"
- "authentication implementation guide"
- "customer feedback themes"

**Weak queries** (too vague):
- "roadmap"
- "guide"
- "feedback"

**Over-specific queries** (too narrow):
- "Q4 2024 product roadmap for mobile app version 3.2 feature X"

### User Context

Always use available user context:
- Query should match their terminology
- Scope to their relevant teamspaces
- Consider their role/department
- Reference their recent pages

## Connected Sources

### Notion Integrations

Search extends beyond Notion pages to:
- Slack messages (if connected)
- Google Drive documents (if connected)
- GitHub issues/PRs (if connected)
- Jira tickets (if connected)

Be aware results may come from these sources.

### Source Attribution

When citing results from connected sources:
- Note the source type in documentation
- Use appropriate mention format
- Verify user has access to the source system


```

### reference/citations.md

```markdown
# Citation Styles

## Basic Page Citation

Always cite sources using Notion page mentions:

```markdown
<mention-page url="https://notion.so/workspace/Page-Title-uuid">Page Title</mention-page>
```

The URL must be provided. The title is optional but improves readability:

```markdown
<mention-page url="https://notion.so/workspace/Page-Title-uuid"/>
```

## Inline Citations

Cite immediately after referenced information:

```markdown
The Q4 revenue increased by 23% quarter-over-quarter (<mention-page url="...">Q4 Financial Report</mention-page>).
```

## Multiple Sources

When information comes from multiple sources:

```markdown
Customer satisfaction has improved across all metrics (<mention-page url="...">Q3 Survey Results</mention-page>, <mention-page url="...">Support Analysis</mention-page>).
```

## Section-Level Citations

For longer sections derived from one source:

```markdown
### Engineering Priorities

According to the <mention-page url="...">Engineering Roadmap 2025</mention-page>:

- Focus on API scalability
- Improve developer experience
- Migrate to microservices architecture
```

## Sources Section

Always include a "Sources" section at document end:

```markdown
## Sources

- <mention-page url="...">Strategic Plan 2025</mention-page>
- <mention-page url="...">Market Analysis Report</mention-page>
- <mention-page url="...">Competitor Research: Q3</mention-page>
- <mention-page url="...">Customer Interview Notes</mention-page>
```

Group by category for long lists:

```markdown
## Sources

### Primary Sources
- <mention-page url="...">Official Roadmap</mention-page>
- <mention-page url="...">Strategy Document</mention-page>

### Supporting Research
- <mention-page url="...">Market Trends</mention-page>
- <mention-page url="...">Customer Feedback</mention-page>

### Background Context
- <mention-page url="...">Historical Analysis</mention-page>
```

## Quoting Content

When quoting directly from source:

```markdown
The product team noted: "We need to prioritize mobile experience improvements" (<mention-page url="...">Product Meeting Notes</mention-page>).
```

For block quotes:

```markdown
> We need to prioritize mobile experience improvements to meet our Q4 goals. This includes performance optimization and UI refresh.
>
> — <mention-page url="...">Product Meeting Notes - Oct 2025</mention-page>
```

## Data Citations

When presenting data, cite the source:

```markdown
| Metric | Q3 | Q4 | Change |
|--------|----|----|--------|
| Revenue | $2.3M | $2.8M | +21.7% |
| Users | 12.4K | 15.1K | +21.8% |

Source: <mention-page url="...">Financial Dashboard</mention-page>
```

## Database Citations

When referencing database content:

```markdown
Based on analysis of the <mention-database url="...">Projects Database</mention-database>, 67% of projects are on track.
```

## User Citations

When attributing information to specific people:

```markdown
<mention-user url="...">Sarah Chen</mention-user> noted in <mention-page url="...">Architecture Review</mention-page> that the microservices migration is ahead of schedule.
```

## Citation Frequency

**Over-citing** (every sentence):
```markdown
The revenue increased (<mention-page url="...">Report</mention-page>). 
Costs decreased (<mention-page url="...">Report</mention-page>). 
Margin improved (<mention-page url="...">Report</mention-page>).
```

**Under-citing** (no attribution):
```markdown
The revenue increased, costs decreased, and margin improved.
```

**Right balance** (grouped citation):
```markdown
The revenue increased, costs decreased, and margin improved (<mention-page url="...">Q4 Financial Report</mention-page>).
```

## Outdated Information

Note when source information might be outdated:

```markdown
The original API design (<mention-page url="...">API Spec v1</mention-page>, last updated January 2024) has been superseded by the new architecture in <mention-page url="...">API Spec v2</mention-page>.
```

## Cross-References

Link to related research documents:

```markdown
## Related Research

This research builds on previous findings:
- <mention-page url="...">Market Analysis - Q2 2025</mention-page>
- <mention-page url="...">Competitor Landscape Review</mention-page>

For implementation details, see:
- <mention-page url="...">Technical Implementation Guide</mention-page>
```

## Citation Validation

Before finalizing research:

✓ Every key claim has a source citation
✓ All page mentions have valid URLs
✓ Sources section includes all cited pages
✓ Outdated sources are noted as such
✓ Direct quotes are clearly marked
✓ Data sources are attributed

## Citation Style Consistency

Choose one citation style and use throughout:

**Inline style** (lightweight):
```markdown
Revenue grew 23% (Financial Report). Customer count increased 18% (Metrics Dashboard).
```

**Formal style** (full mentions):
```markdown
Revenue grew 23% (<mention-page url="...">Q4 Financial Report</mention-page>). Customer count increased 18% (<mention-page url="...">Metrics Dashboard</mention-page>).
```

**Recommend formal style** for most research documentation as it provides clickable navigation.


```

### examples/market-research.md

```markdown
# Example: Market Research

**User Request**: "Research the current state of AI coding assistants market and create a summary document in Notion"

## Workflow

### 1. Search
```
Notion:notion-search
query: "AI coding assistants market"
```
Found 3 relevant pages across Engineering, Strategy, and Product teamspaces.

### 2. Fetch & Analyze
```
Notion:notion-fetch (3x)
```
Extracted market size, competitive landscape, technology trends from source pages.

### 3. Create Documentation
```
Notion:notion-create-pages
```

## Output (Condensed)

```markdown
# AI Coding Assistants Market Research - Oct 2025

## Executive Summary
The AI coding assistant market is experiencing 150%+ YoY growth. GitHub Copilot dominates with 60% share, but specialized tools are gaining traction in specific niches.

## Key Findings

### Market Size and Growth
$800M in 2024 → $2.5B projected by 2026. Developer adoption: 23% (2023) → 47% (2024).
Source: <mention-page url="...">Market Trends Q3 2025</mention-page>

### Competitive Landscape
- GitHub Copilot: 60% (strong IDE integration)
- Cursor: 15% (rapid growth, full IDE)
- Tabnine: 10% (enterprise, on-premise)
- Cody: 5% (codebase-aware)
- CodeWhisperer: 8% (AWS integration)
Source: <mention-page url="...">AI Tools Competitive Analysis</mention-page>

### Technology Trends
Key differentiators: context awareness, customization, multi-modal interfaces, code verification.
Source: <mention-page url="...">Developer Tools Landscape</mention-page>

## Next Steps
1. Monitor Cursor growth and feature releases
2. Evaluate Cody's codebase-aware capabilities
3. Document enterprise security/compliance requirements
4. Track pricing trends
```

## Key Takeaways
- Found relevant pages across multiple teamspaces
- Synthesized competitive, market, and technical perspectives
- Used proper citations linking to source pages
- Created actionable recommendations

```

### examples/technical-investigation.md

```markdown
# Example: Technical Investigation

## User Request

> "Research our current caching strategy and create a technical summary"

## Workflow Execution

### Step 1: Search for Caching Information

```
Notion:notion-search
query: "caching strategy architecture"
query_type: "internal"
teamspace_id: "engineering-teamspace-id"
```

**Results Found:**
- "System Architecture Overview" (Engineering)
- "Redis Implementation Guide" (Backend Docs)
- "Performance Optimization - Q3 2024" (Engineering)
- "API Caching Decision Record" (Architecture)

### Step 2: Fetch Relevant Pages

```
Notion:notion-fetch
id: "system-architecture-page-url"
```

Extracted: Current caching architecture uses Redis for API responses, Memcached for session storage.

```
Notion:notion-fetch
id: "redis-implementation-guide-url"
```

Extracted: Implementation details, TTL settings, invalidation strategies.

```
Notion:notion-fetch
id: "api-caching-decision-record-url"
```

Extracted: Why Redis was chosen over alternatives, trade-offs considered.

### Step 3: Synthesize Findings

**Key findings identified:**
- Two-tier caching: Redis (API responses) + Memcached (sessions)
- TTL strategy: 5 minutes for dynamic data, 1 hour for static
- Invalidation: Event-driven for critical updates
- Performance impact: 75% reduction in database load
- Known issues: Cache stampede on popular endpoints

### Step 4: Create Technical Summary

```
Notion:notion-create-pages

parent: { page_id: "engineering-docs-parent-id" }

pages: [{
  properties: {
    "title": "Technical Summary: Caching Strategy - Oct 2025"
  },
  content: "[Structured technical summary using template]"
}]
```

## Output Document

```markdown
# Technical Summary: Caching Strategy - Oct 2025

## Executive Summary

Our caching infrastructure uses a two-tier approach with Redis for API response caching and Memcached for session management. This strategy has reduced database load by 75% and improved API response times from 200ms to 50ms average.

## Architecture Overview

### Layer 1: API Response Caching (Redis)
**Technology**: Redis 7.0 cluster (3 nodes)
**Purpose**: Cache GET endpoint responses
**TTL Strategy**:
- Dynamic content: 5 minutes
- Static content: 1 hour
- User-specific: 15 minutes

**Source**: <mention-page url="...">System Architecture Overview</mention-page>

### Layer 2: Session Storage (Memcached)
**Technology**: Memcached 1.6
**Purpose**: User session data, temporary state
**TTL**: 24 hours (session lifetime)

## Implementation Details

### Cache Key Format
```
api:v1:{endpoint}:{params_hash}
session:{user_id}:{session_id}
```

### Invalidation Strategy
- **Event-driven**: Critical data changes trigger immediate invalidation
- **Time-based**: TTL expiration for non-critical data
- **Manual**: Admin tools for emergency cache clear

**Source**: <mention-page url="...">Redis Implementation Guide</mention-page>

## Decision Rationale

### Why Redis for API Caching?

**Pros**:
- Advanced data structures (sorted sets, hashes)
- Built-in TTL with automatic eviction
- Pub/sub for cache invalidation events
- Persistence options for durability

**Cons**:
- Higher memory usage than Memcached
- More complex cluster management

**Decision**: Chosen for flexibility and rich feature set needed for API caching.

**Source**: <mention-page url="...">API Caching Decision Record</mention-page>

### Why Memcached for Sessions?

**Pros**:
- Simpler, lighter weight
- Excellent for key-value storage
- Lower memory footprint

**Cons**:
- No persistence
- Limited data structures

**Decision**: Perfect fit for ephemeral session data where simplicity is valued.

## Performance Impact

| Metric | Before Caching | After Caching | Improvement |
|--------|----------------|---------------|-------------|
| Avg Response Time | 200ms | 50ms | 75% faster |
| Database Load | 100% | 25% | 75% reduction |
| Cache Hit Rate | - | 85% | - |
| Peak RPS Handled | 1,000 | 4,000 | 4x increase |

**Source**: <mention-page url="...">Performance Optimization - Q3 2024</mention-page>

## Known Issues & Limitations

### Cache Stampede
**Issue**: When popular cache entries expire, multiple requests hit database simultaneously

**Mitigation**: Implemented probabilistic early expiration and request coalescing

**Status**: Reduced by 90% but not eliminated

### Stale Data Risk
**Issue**: Cached data can be up to TTL duration stale

**Mitigation**: Event-driven invalidation for critical data paths

**Status**: Acceptable trade-off for performance gains

## Monitoring & Observability

**Metrics tracked**:
- Cache hit/miss rates per endpoint
- Memory usage and eviction rates
- Response time distributions
- Invalidation event frequency

**Tools**: DataDog dashboards, CloudWatch alarms

## Future Considerations

1. **Edge Caching**: Evaluate CDN integration for static assets
2. **Cache Warming**: Pre-populate cache for predictable traffic spikes
3. **Adaptive TTLs**: Adjust TTLs based on data change frequency
4. **Regional Caching**: Multi-region cache replication for global performance

## Related Documentation

- <mention-page url="...">System Architecture Overview</mention-page>
- <mention-page url="...">Redis Implementation Guide</mention-page>
- <mention-page url="...">API Caching Decision Record</mention-page>
- <mention-page url="...">Performance Optimization - Q3 2024</mention-page>

## Appendix: Configuration Examples

### Redis Configuration
```yaml
maxmemory: 8gb
maxmemory-policy: allkeys-lru
tcp-keepalive: 60
```

### Common Cache Operations
```python
# Set with TTL
cache.set(key, value, ttl=300)

# Get with fallback
value = cache.get(key) or fetch_from_db(key)

# Invalidate pattern
cache.delete_pattern("api:v1:users:*")
```
```

## Key Success Factors

1. **Multiple source integration**: Combined architecture docs, implementation guides, and decision records
2. **Technical depth**: Included configuration, code examples, metrics
3. **Decision context**: Explained why choices were made, not just what
4. **Practical focus**: Real performance numbers and known issues
5. **Future-looking**: Noted areas for improvement
6. **Well-cited**: Every major point links back to source material

## Workflow Pattern Demonstrated

This example shows the complete research workflow:
- **Scoped search** (teamspace filter for engineering)
- **Multi-page synthesis** (4 different sources)
- **Technical template** (architecture-focused format)
- **Proper placement** (under engineering docs)
- **Comprehensive citations** (links to all sources)


```

### examples/competitor-analysis.md

```markdown
# Example: Competitor Analysis

## User Request

> "Research competitor pricing models and create a comparison document"

## Workflow Execution

### Step 1: Search for Competitor Information

```
Notion:notion-search
query: "competitor pricing"
query_type: "internal"
filters: {
  created_date_range: {
    start_date: "2024-01-01"
  }
}
```

**Results Found:**
- "Competitor Analysis - Stripe" (Product)
- "Market Research Q3 2024" (Strategy)
- "Pricing Strategy Discussion" (Product)
- "Competitor Feature Matrix" (Product)

### Step 2: Fetch and Analyze

```
Notion:notion-fetch for each page
```

**Extracted Information:**

**Stripe**:
- Pay-as-you-go: 2.9% + $0.30 per transaction
- No monthly fees
- Volume discounts available

**Square**:
- Pay-as-you-go: 2.6% + $0.10 per transaction
- Monthly plan: $29/month with lower rates
- Hardware costs separate

**PayPal**:
- Standard: 3.49% + $0.49 per transaction
- Advanced: $30/month + 2.59% + $0.49
- Multi-currency fees

**Adyen**:
- Interchange++ pricing model
- Custom enterprise pricing
- Setup and monthly fees apply

### Step 3: Create Comparison Document

```
Notion:notion-create-pages

pages: [{
  properties: {
    "title": "Competitor Pricing Analysis - Payment Processors"
  },
  content: "[Comparison document using template]"
}]
```

## Output Document

```markdown
# Competitor Pricing Analysis - Payment Processors

**Date**: October 14, 2025  
**Research Team**: Product Strategy

## Executive Summary

We analyzed four major payment processor competitors: Stripe, Square, PayPal, and Adyen. Pricing models vary from simple pay-as-you-go (Stripe) to complex interchange-plus (Adyen). Key insight: All competitors offer volume discounts for high-transaction merchants, with breakpoints typically at $100K/month processing volume.

## Comparison Matrix

| Feature | Stripe | Square | PayPal | Adyen |
|---------|--------|--------|--------|-------|
| **Base Rate** | 2.9% + $0.30 | 2.6% + $0.10 | 3.49% + $0.49 | Interchange++ |
| **Monthly Fee** | $0 | $0-29 | $0-30 | Custom |
| **Volume Discounts** | Yes, >$80K | Yes, >$250K | Yes, >$100K | Yes, custom |
| **Setup Fee** | $0 | $0 | $0 | $1,000-5,000 |
| **Multi-currency** | 1% extra | 3% extra | 3-4% extra | Included |
| **Chargeback Fee** | $15 | $15-25 | $20 | Custom |
| **Target Market** | Startups-Enterprise | Small-Medium | Small-Medium | Enterprise |

## Detailed Analysis

### Stripe

**Pricing Structure**:
- **Standard**: 2.9% + $0.30 per successful card charge
- **Volume discounts**: Available for businesses processing >$80,000/month
- **International cards**: +1% fee
- **Currency conversion**: 1% above market rate

**Strengths**:
- Simple, transparent pricing
- No setup fees or monthly minimums
- Excellent developer experience
- Quick onboarding

**Weaknesses**:
- Higher per-transaction fee for high volume
- Volume discounts less aggressive than Adyen

**Best for**: Startups and growth-stage companies needing quick integration

**Source**: <mention-page url="...">Competitor Analysis - Stripe</mention-page>

### Square

**Pricing Structure**:
- **Pay-as-you-go**: 2.6% + $0.10 per tap, dip, or swipe
- **Keyed-in**: 3.5% + $0.15
- **Plus plan**: $29/month for lower rates (2.5% + $0.10)
- **Premium plan**: Custom pricing

**Strengths**:
- Lowest per-transaction fee for in-person
- All-in-one hardware + software
- No long-term contracts

**Weaknesses**:
- Higher rates for online/keyed transactions
- Hardware costs ($49-$299)
- Less suitable for online-only businesses

**Best for**: Brick-and-mortar retail and restaurants

**Source**: <mention-page url="...">Market Research Q3 2024</mention-page>

### PayPal

**Pricing Structure**:
- **Standard**: 3.49% + $0.49 per transaction
- **Advanced**: $30/month + 2.59% + $0.49
- **Payments Pro**: Additional $30/month for direct credit card processing

**Strengths**:
- Huge customer base (PayPal checkout)
- Buyer protection increases trust
- International reach (200+ countries)

**Weaknesses**:
- Highest per-transaction fees
- Complex fee structure
- Account holds and reserves common

**Best for**: Businesses where PayPal brand trust matters (e-commerce, marketplaces)

**Source**: <mention-page url="...">Pricing Strategy Discussion</mention-page>

### Adyen

**Pricing Structure**:
- **Interchange++**: Actual interchange + scheme fees + fixed markup
- **Setup fee**: $1,000-5,000 (negotiable)
- **Monthly minimum**: Typically $10,000+ processing volume
- **Per-transaction**: Interchange + 0.6% + $0.12 (example)

**Strengths**:
- Most transparent cost structure at scale
- Lowest effective rate for high volume
- True multi-currency (100+ currencies)
- Direct connections to schemes

**Weaknesses**:
- Complex pricing requires analysis
- High minimums ($10K+/month)
- Longer integration time
- Not suitable for small businesses

**Best for**: Enterprise with $1M+/month processing volume

**Source**: <mention-page url="...">Competitor Feature Matrix</mention-page>

## Pricing Trends & Insights

### Volume-Based Discounting
All competitors offer discounts at scale:
- **Entry point**: $80K-$250K/month processing
- **Typical discount**: 10-30 basis points reduction
- **Negotiation leverage**: Begins at $500K/month+

### Hidden Costs to Consider

| Cost Type | Stripe | Square | PayPal | Adyen |
|-----------|--------|--------|--------|-------|
| Chargeback | $15 | $15-25 | $20 | $15-25 |
| Account verification | $0 | $0 | $0 | Varies |
| PCI compliance | $0 | $0 | $0 | $0 |
| Currency conversion | 1% | 3% | 3-4% | 0% |
| Refund fees | Returned | Returned | Not returned | Varies |

### Market Positioning

```
High Volume / Enterprise
    ↑
    |                    Adyen
    |                      
    |         Stripe             
    |    
    |  Square    PayPal
    |
    └──────────────────→
      Small / Simple        Complex / International
```

## Strategic Implications

### For Startups (<$100K/month)
**Recommended**: Stripe
- Lowest friction to start
- No upfront costs
- Great documentation
- Acceptable rates at this scale

### For Growing Companies ($100K-$1M/month)
**Recommended**: Stripe or Square
- Negotiate volume discounts
- Evaluate interchange++ if international
- Consider Square if in-person dominant

### For Enterprises (>$1M/month)
**Recommended**: Adyen or Negotiated Stripe
- Interchange++ models save significantly
- Direct scheme connections
- Multi-region capabilities matter
- ROI on integration complexity

## Recommendations

1. **Immediate**: Benchmark our current 2.8% + $0.25 against Stripe's standard
2. **Short-term**: Request volume discount quote from Stripe at our current $150K/month
3. **Long-term**: Evaluate Adyen when we cross $1M/month threshold

## Next Steps

- [ ] Request detailed pricing proposal from Stripe for volume discounts
- [ ] Create pricing calculator comparing all 4 at different volume levels
- [ ] Interview customers about payment method preferences
- [ ] Analyze our transaction mix (domestic vs international, card types)

## Sources

### Primary Research
- <mention-page url="...">Competitor Analysis - Stripe</mention-page>
- <mention-page url="...">Market Research Q3 2024</mention-page>
- <mention-page url="...">Pricing Strategy Discussion</mention-page>
- <mention-page url="...">Competitor Feature Matrix</mention-page>

### External References
- Stripe.com pricing page (Oct 2025)
- Square pricing documentation
- PayPal merchant fees
- Adyen pricing transparency report
```

## Key Success Factors

1. **Structured comparison**: Matrix format for quick scanning
2. **Multiple dimensions**: Price, features, target market
3. **Strategic recommendations**: Not just data, but implications
4. **Visual elements**: Table and positioning diagram
5. **Actionable next steps**: Clear recommendations
6. **Comprehensive sources**: Internal research + external validation

## Workflow Pattern Demonstrated

- **Date-filtered search** (recent information only)
- **Multiple competitor synthesis** (4 different companies)
- **Comparison template** (matrix + detailed analysis)
- **Strategic layer** (implications and recommendations)
- **Action-oriented** (next steps included)


```