@mohanscodex/spectra-code 0.4.9 → 0.5.0

package/skills/notion-research-documentation/reference/advanced-search.md

@@ -0,0 +1,212 @@
+# 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
+

package/skills/notion-research-documentation/reference/citations.md

@@ -0,0 +1,190 @@
+# 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.
+

package/skills/notion-research-documentation/reference/comparison-format.md

@@ -0,0 +1,37 @@
+# Comparison Format
+
+**When to use**:
+- Evaluating multiple options
+- Tool/vendor selection
+- Approach comparison
+- Decision support
+
+## Characteristics
+
+**Length**: 800-1200 words typically
+
+**Structure**:
+- Overview of what's being compared
+- Comparison matrix table
+- Detailed analysis per option (pros/cons)
+- Clear recommendation with rationale
+- Sources
+
+## Template
+
+See [comparison-template.md](comparison-template.md) for the full template.
+
+## Best For
+
+- Decision support with multiple options
+- Tool or vendor selection
+- Comparing different technical approaches
+- Evaluating trade-offs between alternatives
+
+## Example Use Cases
+
+- "Compare the three database options discussed in our tech docs"
+- "What are the pros and cons of each deployment approach?"
+- "Compare the vendor proposals"
+- "Evaluate the different authentication methods we've documented"
+

package/skills/notion-research-documentation/reference/comparison-template.md

@@ -0,0 +1,44 @@
+# Comparison Template
+
+Use when researching multiple options or alternatives. See [comparison-format.md](comparison-format.md) for when to use this format.
+
+```markdown
+# [Topic] Comparison
+
+## Overview
+[Brief introduction to what's being compared and why]
+
+## Comparison Matrix
+
+| Criteria | Option A | Option B | Option C |
+|----------|----------|----------|----------|
+| [Criterion 1] | [Rating/Details] | [Rating/Details] | [Rating/Details] |
+| [Criterion 2] | [Rating/Details] | [Rating/Details] | [Rating/Details] |
+
+## Detailed Analysis
+
+### Option A
+**Pros**:
+- [Advantage]
+- [Advantage]
+
+**Cons**:
+- [Disadvantage]
+- [Disadvantage]
+
+**Best for**: [Use case]
+
+**Source**: <mention-page url="...">Source Page</mention-page>
+
+[Repeat for each option]
+
+## Recommendation
+
+**Selected option**: [Choice]
+
+**Rationale**: [Why this option is best given the context]
+
+## Sources
+[List all consulted pages]
+```
+

package/skills/notion-research-documentation/reference/comprehensive-report-format.md

@@ -0,0 +1,41 @@
+# 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"
+

package/skills/notion-research-documentation/reference/comprehensive-report-template.md

@@ -0,0 +1,64 @@
+# Comprehensive Report Template
+
+Use for in-depth research requiring extensive analysis. See [comprehensive-report-format.md](comprehensive-report-format.md) for when to use this format.
+
+```markdown
+# [Report Title]
+
+## Executive Summary
+[One paragraph summarizing the entire report]
+
+## Background & Context
+[Why this research was conducted, what questions it addresses]
+
+## Methodology
+- Sources consulted: [number] Notion pages across [teamspaces]
+- Time period: [if relevant]
+- Scope: [what was included/excluded]
+
+## Key Findings
+
+### [Major Theme 1]
+**Summary**: [One sentence]
+
+**Details**:
+- [Supporting point with evidence]
+- [Supporting point with evidence]
+- [Supporting point with evidence]
+
+**Sources**: [Page mentions]
+
+### [Major Theme 2]
+[Repeat structure]
+
+## Data & Evidence
+
+[Tables, quotes, specific data points]
+
+## Implications
+
+### Short-term
+[Immediate implications]
+
+### Long-term
+[Strategic implications]
+
+## Recommendations
+
+### Priority 1: [High priority action]
+- **What**: [Specific action]
+- **Why**: [Rationale]
+- **How**: [Implementation approach]
+
+### Priority 2: [Medium priority action]
+[Repeat structure]
+
+## Appendix
+
+### Additional Resources
+- [Related pages]
+
+### Open Questions
+- [Unanswered questions for future research]
+```
+

package/skills/notion-research-documentation/reference/format-selection-guide.md

@@ -0,0 +1,95 @@
+# 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
+