Research

Technical research:

1. Define: Problem, requirements, constraints
2. Discover: GitHub, HuggingFace, Context7 docs
3. Evaluate: Apply framework checklist, test minimal example
4. Decide: Build vs buy, document rationale

Output: Research report with question, answer, confidence, sources

Quick Reference

Part 1: Market Research

Company Profile Framework

company_profile = {
    # Basics
    'name': str,
    'website': str,
    'industry': str,
    'employee_count': int,
    'revenue_estimate': str,  # "$5-10M", "$10-50M"

    # Operations
    'field_vs_office': {'field': int, 'office': int},
    'service_area': list[str],  # States/regions
    'trades': list[str],  # Electrical, HVAC, Plumbing

    # Technology
    'software_stack': {
        'crm': str,
        'project_mgmt': str,
        'accounting': str,
        'field_service': str,
        'other': list[str]
    },

    # Sales Intel
    'pain_signals': list[str],
    'growth_indicators': list[str],
    'failed_implementations': list[str],
    'decision_makers': list[dict]
}

Pain Signal Detection

Market Research Workflow

Step 1: Basic Discovery
└── Website, LinkedIn, Google News, Glassdoor

Step 2: Tech Stack
└── Job postings, integrations page, case studies

Step 3: Pain Signals
└── Reviews, social mentions, forum posts

Step 4: Decision Makers
└── LinkedIn Sales Nav, company about page

Step 5: Synthesize
└── Generate company profile, score against ICP

Competitive Positioning

When researching competitors for a prospect:

1. What are they using now?
2. How long have they used it?
3. What's broken? (Check reviews, Reddit, forums)
4. What would make them switch?
5. Who else are they evaluating?

Part 2: Technical Research

Stack Constraints (Tim's Environment)

constraints:
  llm_providers:
    preferred:
      - anthropic  # Claude - primary
      - google     # Gemini - multimodal
      - openrouter # DeepSeek, Qwen, Yi - cost optimization
    forbidden:
      - openai     # NO OpenAI

  infrastructure:
    compute: runpod_serverless
    database: supabase
    hosting: vercel
    local: ollama  # M1 Mac compatible

  frameworks:
    preferred:
      - langgraph  # Over langchain
      - fastmcp    # For MCP servers
      - pydantic   # Data validation
    avoid:
      - langchain  # Too abstracted
      - autogen    # Complexity

  development:
    machine: m1_mac
    ide: cursor, claude_code
    version_control: github

LLM Selection Matrix

Cost Optimization Rule: Use Chinese LLMs (DeepSeek, Qwen) for 90%+ cost savings on bulk/routine tasks. Reserve Claude/Gemini for complex reasoning.

Framework Evaluation Checklist

## [Framework Name] Evaluation

### Basic Info
- [ ] GitHub stars / activity
- [ ] Last commit date
- [ ] Maintainer reputation
- [ ] License type
- [ ] Documentation quality

### Technical Fit
- [ ] Python 3.11+ compatible
- [ ] M1 Mac compatible
- [ ] Async support
- [ ] Type hints / Pydantic
- [ ] MCP integration possible

### Ecosystem
- [ ] Active Discord/community
- [ ] Stack Overflow presence
- [ ] Tutorial availability
- [ ] Example projects

### Red Flags
- [ ] OpenAI-only
- [ ] Unmaintained (>6 months)
- [ ] Poor documentation
- [ ] Heavy dependencies
- [ ] Vendor lock-in

API Evaluation Template

api_evaluation:
  name: ""
  provider: ""
  documentation_url: ""

  access:
    auth_method: ""  # API key, OAuth, etc.
    rate_limits:
      requests_per_minute: 0
      tokens_per_minute: 0
    quotas: ""

  pricing:
    model: ""  # per request, per token, subscription
    free_tier: ""
    cost_estimate: ""  # for our use case

  developer_experience:
    sdk_quality: ""  # 1-5
    documentation: ""  # 1-5
    error_messages: ""  # 1-5
    response_time: ""  # ms

  integration:
    existing_mcps: []
    sdk_languages: []
    webhook_support: bool

  verdict: ""  # USE, MAYBE, SKIP
  notes: ""

Technical Research Workflow

┌─────────────────────────────────────────────┐
│ 1. DEFINE                                    │
│    What problem are we solving?              │
│    What are the requirements?                │
│    What are the constraints?                 │
└─────────────────┬───────────────────────────┘
                  ▼
┌─────────────────────────────────────────────┐
│ 2. DISCOVER                                  │
│    Search GitHub, HuggingFace, blogs         │
│    Check Context7 for docs                   │
│    Review existing tk_projects               │
└─────────────────┬───────────────────────────┘
                  ▼
┌─────────────────────────────────────────────┐
│ 3. EVALUATE                                  │
│    Apply checklist above                     │
│    Test minimal example                      │
│    Check M1 compatibility                    │
└─────────────────┬───────────────────────────┘
                  ▼
┌─────────────────────────────────────────────┐
│ 4. DECIDE                                    │
│    Build vs buy vs skip                      │
│    Document decision rationale               │
│    Update AI_MODEL_SELECTION_GUIDE if LLM    │
└─────────────────────────────────────────────┘

MCP Discovery Workflow

# When looking for MCP capabilities:

1. Check mcp-server-cookbook first
   └── /Users/tmkipper/Desktop/tk_projects/mcp-server-cookbook/

2. Search official MCP servers
   └── github.com/modelcontextprotocol/servers

3. Search community servers
   └── github.com search: "mcp server" + [capability]

4. Check if FastMCP wrapper exists
   └── Can we build it quickly?

5. Evaluate build vs. use existing
   └── Time to integrate vs. time to build

Part 3: Combined Research Outputs

Research Report Template

research_report:
  title: ""
  type: ""  # market, technical, hybrid
  date: ""
  researcher: ""

  # Executive Summary
  summary:
    question: ""
    answer: ""
    confidence: ""  # high, medium, low

  # Findings
  market_findings:
    companies_analyzed: []
    competitive_landscape: ""
    market_size: ""
    trends: []

  technical_findings:
    frameworks_evaluated: []
    recommended_stack: {}
    integration_considerations: []
    cost_analysis: {}

  # Recommendations
  recommendations:
    primary: ""
    alternatives: []
    risks: []
    next_steps: []

  # Sources
  sources:
    - type: ""
      url: ""
      date_accessed: ""
      key_findings: []

Decision Matrix Template

Integration Notes

Market Research

• Feeds into: dealer-scraper (enrichment), sales-agent (qualification)
• Data sources: LinkedIn, Glassdoor, Indeed, G2, Capterra, Google
• Pairs with: sales-outreach-skill (messaging), opportunity-evaluator-skill (deals)

Technical Research

• References: AI_MODEL_SELECTION_GUIDE.md, runpod-deployment-skill
• Projects: ai-cost-optimizer, mcp-server-cookbook
• Tools: Context7 MCP for docs, HuggingFace MCP for models
• Pairs with: opportunity-evaluator-skill (build vs partner decisions)

Reference Files

Market Research

• reference/market.md - Company profiles, tech stack discovery, ICP, competitive analysis

Technical Research

• reference/technical.md - Framework comparison, LLM evaluation, API patterns, MCP discovery

Emit Outcome Sidecar

As the final step, write to ~/.claude/skill-analytics/last-outcome-research.json:

{"ts":"[UTC ISO8601]","skill":"research","version":"1.0.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"sources_consulted":[n],"findings_synthesized":[n],"recommendations":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

Use status "partial" if some stages failed but results were produced. Use "error" only if no output was generated.