neotoma 0.3.0 → 0.3.2

package/docs/releases/archived/aspirational/v1.0.0/cross_platform_signal_detection.md

@@ -1,181 +0,0 @@
-## Cross-Platform Signal Detection Strategy
-### Purpose
-When generating leads for direct outreach, we need to decide: Should we check posts on the target platform (where we're reaching out) or posts on linked platforms (from their profile)? This document defines the strategy.
-### Recommendation: Check Both, Prioritize Target Platform
-**Strategy**: Check target platform first (most relevant), then enrich with linked platforms (additional signals)
-**Rationale**:
-- **Target platform posts**: Most relevant to outreach context, easier to access, directly related to platform you're using
-- **Linked platform posts**: Additional signals, people often post more on some platforms (Twitter/X), fills gaps if target platform has limited activity
-- **Combined approach**: Maximum signal detection while maintaining relevance
-### Signal Detection Priority
-#### 1. Target Platform (Primary — Weight 1.0)
-**Check posts/activity on the platform you're reaching out on:**
-- **LinkedIn Outreach**: Check LinkedIn posts, LinkedIn activity feed
-- **Twitter/X Outreach**: Check Twitter/X posts, Twitter/X activity feed
-- **GitHub Outreach**: Check GitHub activity, repositories, commits
-**Why Primary**:
-- Most relevant to outreach context
-- Shows activity on platform you're using
-- Easier to access (already have platform access)
-- Directly related to how you found them
-**Detection**:
-- Search recent posts (last 30-90 days)
-- Check activity feed for AI tool mentions
-- Look for subscription mentions, AI tool usage
-- Check engagement patterns (likes, comments, shares)
-#### 2. Linked Platforms (Secondary — Weight 0.6)
-**Check posts/activity on platforms linked from their profile:**
-- **From LinkedIn**: Extract Twitter/X handle, GitHub username (if linked in profile)
-- **From Twitter/X**: Extract LinkedIn URL, GitHub username (if linked in bio)
-- **From GitHub**: Extract Twitter/X handle, LinkedIn URL (if linked in profile)
-**Why Secondary**:
-- Additional signals (people often post more on Twitter/X than LinkedIn)
-- Fills gaps if target platform has limited activity
-- Provides cross-platform validation
-- But less directly relevant to outreach context
-**Detection**:
-- Extract linked platform handles/URLs from profile
-- Search linked platform posts for subscription mentions
-- Check linked platform activity for AI tool usage
-- Aggregate signals across platforms
-**Limitations**:
-- Not all profiles link other platforms
-- Requires cross-platform API access
-- May have rate limits
-- Some platforms don't allow easy extraction of linked profiles
-### Implementation by Platform
-#### LinkedIn Sales Navigator
-**Target Platform (LinkedIn)**:
-- Check LinkedIn posts for subscription mentions
-- Check LinkedIn activity feed for AI tool usage
-- Search LinkedIn profile/headline for keywords
-**Linked Platforms**:
-- Extract Twitter/X handle from LinkedIn profile (if linked)
-- Extract GitHub username from LinkedIn profile (if linked)
-- Check Twitter/X posts (if handle found)
-- Check GitHub activity (if username found)
-**Output**: `linkedin_signals` (primary), `twitter_signals` (secondary), `github_signals` (secondary)
-#### Twitter/X Search
-**Target Platform (Twitter/X)**:
-- Check Twitter/X posts for subscription mentions
-- Check Twitter/X bio for subscription mentions
-- Search Twitter/X activity feed for AI tool usage
-**Linked Platforms**:
-- Extract LinkedIn URL from Twitter/X bio (if linked)
-- Extract GitHub username from Twitter/X bio (if linked)
-- Check LinkedIn posts (if URL found)
-- Check GitHub activity (if username found)
-**Output**: `twitter_signals` (primary), `linkedin_signals` (secondary), `github_signals` (secondary)
-#### GitHub User Search
-**Target Platform (GitHub)**:
-- Check GitHub repositories for AI-related projects
-- Check GitHub activity for AI tool usage
-- Search GitHub profile/bio for keywords
-**Linked Platforms**:
-- Extract Twitter/X handle from GitHub profile (if linked)
-- Extract LinkedIn URL from GitHub profile (if linked)
-- Check Twitter/X posts (if handle found)
-- Check LinkedIn posts (if URL found)
-**Output**: `github_signals` (primary), `twitter_signals` (secondary), `linkedin_signals` (secondary)
-### Signal Aggregation in Unified Lead Manager
-**Combining Signals Across Platforms**:
-```javascript
-// Pseudo-code for signal aggregation
-function aggregateSignals(lead) {
-  const targetPlatformSignals = getTargetPlatformSignals(lead); // Weight 1.0
-  const linkedPlatformSignals = getLinkedPlatformSignals(lead); // Weight 0.6
-  const aggregatedScore =
-    targetPlatformSignals.score * 1.0 + linkedPlatformSignals.score * 0.6;
-  return {
-    ...lead,
-    aggregated_signals: aggregatedScore,
-    signal_sources: {
-      target: targetPlatformSignals,
-      linked: linkedPlatformSignals,
-    },
-  };
-}
-```
-**Scoring Logic**:
-- Target platform signals: Full weight (1.0)
-- Linked platform signals: Reduced weight (0.6)
-- Combined score: Weighted average
-- Missing linked platform: No penalty (just use target platform signals)
-### Benefits of Cross-Platform Detection
-**Advantages**:
-1. **More Signals**: People post more on some platforms (Twitter/X) than others (LinkedIn)
-2. **Gap Filling**: If target platform has limited activity, linked platforms provide signals
-3. **Validation**: Cross-platform signals validate each other (more confidence)
-4. **Comprehensive**: Captures full picture of user's AI tool usage
-**Example**:
-- LinkedIn profile: Limited posts, but links Twitter/X
-- Twitter/X posts: Multiple mentions of "ChatGPT Plus", "Claude Pro"
-- Result: Strong subscription signals from Twitter/X enrich LinkedIn lead
-### Limitations and Mitigation
-**Limitations**:
-- Not all profiles link other platforms
-- Cross-platform API access required
-- Rate limits may apply
-- Some platforms don't expose linked profiles easily
-**Mitigation**:
-- Make linked platform detection optional (graceful degradation)
-- Prioritize target platform (works even if linked platforms unavailable)
-- Cache linked platform data to reduce API calls
-- Use rate limiting and delays for cross-platform checks
-### Recommended Workflow
-**For Each Lead**:
-1. **Check Target Platform** (Required):
-   - Search posts on platform you're reaching out on
-   - Extract subscription signals, AI tool usage
-   - Score based on target platform signals
-2. **Extract Linked Platforms** (Optional):
-   - Parse profile for linked platform handles/URLs
-   - If found, check linked platform posts
-   - Extract additional signals from linked platforms
-3. **Aggregate Signals**:
-   - Combine target platform signals (weight 1.0) + linked platform signals (weight 0.6)
-   - Calculate aggregated ICP match score
-   - Flag leads with strong signals from any platform
-4. **Export with Signal Sources**:
-   - Include `target_platform_signals` field
-   - Include `linked_platform_signals` field
-   - Include `aggregated_signals` field
-   - Include `signal_sources` breakdown
-### Implementation Notes
-**Tool Updates Needed**:
-1. **LinkedIn Sales Navigator Tool**:
-   - Extract Twitter/X handle, GitHub username from LinkedIn profiles
-   - Check LinkedIn posts (target platform)
-   - Check Twitter/X posts (if handle found)
-   - Check GitHub activity (if username found)
-2. **Twitter/X Search Tool**:
-   - Extract LinkedIn URL, GitHub username from Twitter/X bios
-   - Check Twitter/X posts (target platform)
-   - Check LinkedIn posts (if URL found)
-   - Check GitHub activity (if username found)
-3. **Unified Lead Manager**:
-   - Aggregate signals across platforms
-   - Weight target platform higher than linked platforms
-   - Export signal breakdown for transparency
-**API Requirements**:
-- LinkedIn API: Profile data, posts (if available)
-- Twitter/X API: Bio parsing, posts search
-- GitHub API: Profile data, activity feed
-**Rate Limits**:
-- Respect platform rate limits
-- Cache linked platform data
-- Use delays between cross-platform checks
-- Make linked platform checks optional (don't fail if unavailable)
-### Success Metrics
-**Signal Detection Rate**:
-- Target platform signals: 60-70% of leads (expected)
-- Linked platform signals: 30-40% of leads (if profiles link platforms)
-- Combined signals: 70-80% of leads (target + linked)
-**Signal Quality**:
-- Target platform signals: Higher relevance (weight 1.0)
-- Linked platform signals: Supporting evidence (weight 0.6)
-- Combined score: More accurate ICP matching
-**Performance**:
-- Target platform check: Fast (already have access)
-- Linked platform check: Slower (requires cross-platform API calls)
-- Recommendation: Make linked platform checks optional/async

package/docs/releases/archived/aspirational/v1.0.0/deployment_strategy.md

@@ -1,115 +0,0 @@
-## Release v1.0.0 — Deployment and Rollback Strategy
-### Purpose
-This document defines the deployment strategy for v1.0.0, including staging deployment, production deployment, and rollback procedures.
-**Strategy**: `staging_first` — All releases deploy to staging first, validate, then deploy to production at neotoma.io.
-**Note**: All releases (marketed and not marketed) deploy to production at neotoma.io. Staging is used for validation before production deployment.
-**Related Documents:**
-- `release_plan.md` — Release overview and scope
-- `acceptance_criteria.md` — Release-level acceptance criteria
-- `pre_mortem.md` — Failure mode analysis
-- `status.md` — Current status and progress tracking
-### 1. Deployment Strategy: Staging First
-#### 1.1 Staging Deployment
-**Pre-deployment Checklist:**
-- All P0 FUs marked `completed` with passing tests
-- Integration test suite passes (see `integration_tests.md`)
-- Database migrations tested in staging environment
-- Environment variables validated
-- SSL certificates valid
-- Monitoring and alerting configured
-**Deploy to Staging:**
-1. Tag release: `git tag v1.0.0-staging`
-2. Deploy application to staging.neotoma.app
-3. Run database migrations
-4. Verify health checks pass
-**Staging Validation:**
-- Run full integration test suite against staging
-- Run smoke tests (core workflows)
-- Performance benchmarks:
-  - Upload latency P95 < 5s
-  - Search latency P95 < 500ms
-- Manual testing:
-  - Upload various file types (PDF, CSV, images)
-  - Verify extraction, timeline, search
-  - Test MCP access with Claude/ChatGPT
-  - Test auth and RLS isolation
-**Staging Sign-Off Criteria:**
-- All integration tests pass
-- All smoke tests pass
-- Performance benchmarks met
-- Manual testing complete with no critical issues
-- Sign-off from owner (Mark Hendrickson)
-#### 1.2 Production Deployment
-**Pre-deployment:**
-1. Tag production release: `git tag v1.0.0`
-2. Backup production database
-3. Notify monitoring systems (expect deploy)
-4. Prepare rollback plan
-**Deploy to Production:**
-1. Deploy application to app.neotoma.app
-2. Run database migrations
-3. Verify health checks pass
-4. Enable production traffic
-**Post-deployment Validation:**
-- Run smoke tests against production
-- Verify core metrics:
-  - Upload success rate ≥ 95%
-  - P95 latency < 5s
-  - No orphans/cycles in graph
-- Monitor for 1 hour:
-  - Error rates < 1%
-  - Latency within SLAs
-  - No alerts triggered
-**Production Sign-Off:**
-- All smoke tests pass
-- Metrics within acceptable ranges
-- No critical errors or alerts
-- Sign-off from owner
-### 2. Rollback Plan
-#### 2.1 Rollback Triggers
-- Critical errors affecting > 10% of requests
-- Data integrity issues (orphans/cycles detected)
-- Upload success rate < 80%
-- P95 latency > 10s for > 5 minutes
-- Database migration failure
-- Security vulnerability discovered
-#### 2.2 Rollback Procedure
-**Immediate Actions:**
-1. **STOP**: Halt all deployment activities
-2. **ALERT**: Notify owner immediately
-3. **ASSESS**: Determine severity and impact
-**Application Rollback:**
-1. Revert to previous release tag: `v0.9.x` (last known-good)
-2. Redeploy previous version
-3. Verify health checks pass
-**Database Rollback (if needed):**
-1. Assess migration impact
-2. If safe: Run down migrations to revert schema
-3. If unsafe: Restore from pre-deployment backup
-4. Verify data integrity after restore
-**Post-Rollback Validation:**
-1. Run smoke tests against rolled-back version
-2. Verify core metrics restored
-3. Monitor for 30 minutes
-4. Investigate root cause
-**Communication:**
-- Internal: Post-mortem document
-- External (if users affected): Status page update, apology, ETA for fix
-#### 2.3 Rollback Testing
-- Rollback procedure tested in staging before production deploy
-- Database restore tested with production snapshot (anonymized)
-- Rollback time target: < 15 minutes from decision to restored service
-### 3. Deployment Timeline
-**Staging Deployment:**
-- Target: T-3 days (3 days before production)
-- Duration: ~2 hours (including validation)
-**Production Deployment:**
-- Target: Day 0 (launch date)
-- Duration: ~1 hour (including validation)
-- Maintenance window: TBD (if needed)
-### 4. Related Documents
-- `release_plan.md` — Release overview and scope
-- `acceptance_criteria.md` — Release-level acceptance criteria
-- `pre_mortem.md` — Failure mode analysis
-- `monitoring_plan.md` — Post-release monitoring and observability
-- `status.md` — Current status and progress tracking

package/docs/releases/archived/aspirational/v1.0.0/discovery_checklist.md

@@ -1,195 +0,0 @@
-## Discovery Planning Checklist
-### Purpose
-This checklist ensures all discovery planning needs are documented and ready for execution. Use this to verify completeness before starting discovery activities.
-### Week -10 to -9: Discovery Infrastructure Setup
-**Lead Sourcing Tools:**
-- [ ] Build LinkedIn Sales Navigator export tool (`scripts/discovery/linkedin_sales_navigator_export.js`)
-- [ ] Build LinkedIn Connections export tool (`scripts/discovery/linkedin_connections_export.js`)
-- [ ] Build Twitter/X search tool (`scripts/discovery/twitter_search.js`)
-- [ ] Build Indie Hackers search tool (`scripts/discovery/indie_hackers_search.js`)
-- [ ] Build GitHub user search tool (`scripts/discovery/github_search.js`)
-- [ ] Build Reddit/Discord search tool (`scripts/discovery/reddit_discord_search.js`)
-- [ ] Build unified lead manager (`scripts/discovery/unified_lead_manager.js`)
-- [ ] Build recruitment log importer (`scripts/discovery/import_to_recruitment_log.js`)
-- [ ] Create `.env.example` template for API credentials
-- [ ] Create `scripts/discovery/README.md` with usage documentation
-- [ ] Create `scripts/discovery/agent_instructions.md` for agent-driven execution
-**API Credentials Setup:**
-- [ ] Configure Twitter/X API credentials (if using API)
-- [ ] Configure GitHub personal access token
-- [ ] Set up LinkedIn Sales Navigator account (if using)
-- [ ] Configure Reddit API credentials (if using API)
-- [ ] Store credentials securely in `.env` (not committed)
-**Cross-Platform Signal Detection:**
-- [ ] Implement target platform post checking (LinkedIn, Twitter/X, GitHub)
-- [ ] Implement linked platform extraction (Twitter/X handle, GitHub username from profiles)
-- [ ] Implement linked platform post checking (cross-platform signals)
-- [ ] Implement signal aggregation with weighting (target platform 1.0, linked platforms 0.6)
-**Filtering Implementation:**
-- [ ] Implement enhanced filtering criteria (see `discovery_filtering_criteria.md`)
-- [ ] Load filtering keywords (see `discovery_filtering_keywords.md`)
-- [ ] Implement subscription detection (multi-method: self-reported, bio mentions, proxy indicators)
-- [ ] Implement ICP match scoring system
-**Documentation:**
-- [ ] Review `discovery_lead_sourcing_tools.md` for tool specifications
-- [ ] Review `discovery_filtering_criteria.md` for filtering criteria
-- [ ] Review `discovery_filtering_keywords.md` for keyword reference
-- [ ] Review `subscription_detection_strategy.md` for detection methods
-- [ ] Review `cross_platform_signal_detection.md` for signal detection strategy
-### Week -8: Discovery Execution Setup
-**Lead Generation:**
-- [ ] Execute LinkedIn Sales Navigator tool (or manual export)
-- [ ] Execute LinkedIn Connections export tool
-- [ ] Execute Twitter/X search tool
-- [ ] Execute Indie Hackers search tool
-- [ ] Execute GitHub user search tool
-- [ ] Execute Reddit/Discord search tool
-- [ ] Run unified lead manager to combine and score leads
-- [ ] Review unified lead list for quality
-  - [ ] Verify ICP match scores are reasonable
-  - [ ] Check for duplicate leads
-  - [ ] Prioritize leads with subscription signals
-- [ ] Import unified leads into participant recruitment log
-**Screening Survey Setup:**
-- [ ] Create screening survey (Survey Path)
-- [ ] Include enhanced ICP qualification questions (see `value_discovery_plan.md`)
-- [ ] Include subscription detection questions (primary method)
-- [ ] Set up survey distribution (Indie Hackers, Reddit, Discord, Hacker News)
-- [ ] Prepare survey response tracking
-**Outreach Preparation:**
-- [ ] Prepare personalized outreach templates (Direct Outreach Path)
-- [ ] Review response rate optimization strategies (see `participant_recruitment_log.md`)
-- [ ] Set up calendar scheduling tool (Calendly/Cal.com)
-- [ ] Prepare gift card distribution process ($25-50 per participant)
-- [ ] Review early access strategy (conditional offering)
-**Feasibility Validation:**
-- [ ] Set up test environment for OCR determinism testing
-- [ ] Prepare test corpus (20+ representative documents)
-- [ ] Begin OCR reproducibility tests
-- [ ] Begin low-confidence flagging tests
-### Week -8 to -6: Value Discovery
-**Participant Recruitment:**
-- [ ] Send 40-50 outreach messages (Survey Path + Direct Outreach Path)
-- [ ] Track responses in `participant_recruitment_log.md`
-- [ ] Schedule 17-18 interviews (accounting for no-shows)
-- [ ] Send calendar confirmations with brief screening question (Direct Outreach Path)
-- [ ] Send gift card reminders
-**Value Discovery Interviews:**
-- [ ] Conduct 13 interviews (8 AI-Native Operators + 5 Knowledge Workers)
-- [ ] Follow Mom Test methodology (see `value_discovery_plan.md`)
-- [ ] Validate problem exists (AI lacks personal data access)
-- [ ] Test solution only if problem validated (MCP-based solution)
-- [ ] Look for commitment signals (time, money, workarounds)
-- [ ] Document findings in interview notes
-**Feasibility Validation:**
-- [ ] Complete OCR reproducibility tests (100 runs per document)
-- [ ] Complete low-confidence flagging tests
-- [ ] Complete schema detection accuracy tests
-- [ ] Complete MCP query performance tests
-- [ ] Document results in `feasibility_validation.md`
-### Week -7 to -6: Usability Discovery
-**Participant Selection:**
-- [ ] Select 8 participants from value discovery (subset who validated problem)
-- [ ] Invite to usability testing sessions
-- [ ] Schedule 8 prototype testing sessions
-**Prototype Testing:**
-- [ ] Prepare clickable prototype (upload → extraction → MCP query)
-- [ ] Conduct 8 usability testing sessions (think-aloud protocol)
-- [ ] Test Scenario 1: Upload and view extracted data
-- [ ] Test Scenario 2: Query personal data via AI (MCP simulation)
-- [ ] Test Scenario 3: Ask multiple questions across documents
-- [ ] Test Scenario 4: Timeline discovery
-- [ ] Collect SUS scores
-- [ ] Document usability issues and blockers
-### Week -6 to -5: Business Viability Discovery
-**Participant Selection:**
-- [ ] Select 8 participants from value discovery (AI-Native Operators with high interest + commitment signals)
-- [ ] Invite to pricing interviews
-- [ ] Schedule 8 pricing interviews
-**Pricing Interviews:**
-- [ ] Conduct 8 willingness-to-pay interviews
-- [ ] Follow Mom Test methodology (see `business_viability_discovery_plan.md`)
-- [ ] Ask about past purchasing behavior (not hypotheticals)
-- [ ] Test Van Westendorp Price Sensitivity Meter
-- [ ] Identify value drivers for paying
-- [ ] Document pricing findings
-### Week -5 to -4: Discovery Synthesis
-**Analysis:**
-- [ ] Analyze value discovery findings
-- [ ] Analyze usability discovery findings
-- [ ] Analyze business viability discovery findings
-- [ ] Analyze feasibility validation results
-- [ ] Compare against success criteria (see `discovery_plan.md`)
-**Reporting:**
-- [ ] Generate `value_discovery_report.md`
-- [ ] Generate `usability_discovery_report.md`
-- [ ] Generate `business_viability_report.md`
-- [ ] Generate `feasibility_validation.md`
-- [ ] Generate `discovery_report.md` (combined synthesis)
-**Go/No-Go Decision:**
-- [ ] Review go/no-go criteria (see `discovery_plan.md`)
-- [ ] Make go/no-go/pivot decision
-- [ ] Update release plan based on learnings (if pivot)
-- [ ] Document decision in `status.md`
-### Continuous Discovery (Week 0 to Week 12)
-**Weekly Interviews:**
-- [ ] Schedule 2-3 user interviews per week
-- [ ] Focus on feedback on completed features
-- [ ] Test MCP workflow assumptions
-- [ ] Document findings in `continuous_discovery_log.md`
-**Prototype Testing:**
-- [ ] Test after FU-300 (Design System)
-- [ ] Test after FU-700 (Authentication UI)
-- [ ] Test after any other UI FUs
-**Beta Testing (Week 11-12):**
-- [ ] Invite discovery participants + early access signups
-- [ ] Provide full access to MVP
-- [ ] Collect feedback and bug reports
-- [ ] Test end-to-end workflows
-- [ ] Validate MCP connection setup
-### Key Documents Reference
-**Lead Sourcing and Filtering:**
-- `discovery_lead_sourcing_tools.md` — Tool specifications
-- `discovery_filtering_criteria.md` — Enhanced ICP matching criteria
-- `discovery_filtering_keywords.md` — Complete keyword reference
-- `subscription_detection_strategy.md` — Subscription detection methods
-- `cross_platform_signal_detection.md` — Cross-platform signal strategy
-**Discovery Activities:**
-- `value_discovery_plan.md` — Value discovery details
-- `usability_discovery_plan.md` — Usability discovery details
-- `business_viability_discovery_plan.md` — Business viability discovery details
-- `feasibility_validation_plan.md` — Feasibility validation details
-- `continuous_discovery_plan.md` — Continuous discovery details
-**Recruitment:**
-- `participant_recruitment_log.md` — Recruitment tracking and templates
-- `discovery_plan.md` — Discovery overview and coordination
-### Success Criteria Summary
-**Value Discovery:**
-- ≥70% validate problem exists
-- ≥60% express interest in MCP solution
-- ≥50% care about deterministic structured data access
-- ≥60% see value in "upload once, query forever" workflow
-- Commitment signals present in ≥70% of interviews
-**Usability Discovery:**
-- ≥80% complete upload without help
-- ≥70% complete MCP query successfully
-- ≥70% understand uploaded data becomes queryable via AI
-- SUS score ≥70
-- ≤2 critical usability blockers
-**Business Viability:**
-- ≥50% express willingness to pay ≥€25/month
-- ≥30% express willingness to pay ≥€50/month
-- Optimal price point within €25-€125 range
-- ≥60% prefer monthly subscription
-**Feasibility Validation:**
-- 100% OCR reproducibility
-- Low-confidence flagging accuracy ≥85%
-- Schema detection accuracy >85%
-- MCP reliability ≥99.9%
-- Performance targets met (<5s P95 upload, <500ms P95 MCP query)
-### Notes
-- All discovery documents are complete and ready for execution
-- Lead sourcing tools can be built Week -10 to -9 (2 weeks before discovery starts)
-- Agent-driven execution supported after API credential setup
-- Two recruitment paths: Survey Path (community posts) and Direct Outreach Path (personalized messages)
-- Subscription detection uses multi-method approach (self-reported primary, bio mentions secondary, proxy indicators tertiary)