neotoma 0.3.0 → 0.3.2

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

@@ -1,122 +0,0 @@
-## Release v1.0.0 — Pre-Mortem: Failure Mode Analysis
-### Purpose
-Before execution, identify likely failure modes and mitigation strategies to proactively address risks before they materialize.
-**Review Schedule:**
-- **Checkpoint 0.5** (after discovery): Update based on discovery findings
-- **Checkpoint 1** (mid-release): Update based on execution progress
-- **Checkpoint 2** (pre-deployment): Final review before production
-**Related Documents:**
-- `release_plan.md` — Release overview and scope
-- `deployment_strategy.md` — Deployment and rollback procedures
-- `status.md` — Current status and progress tracking
-### 1. Identified Failure Modes
-#### Failure Mode 1: RLS Implementation Issues (Per-User Isolation)
-- **Probability**: Low (no existing data/users to migrate for MVP)
-- **Impact**: Medium (new users affected, but no legacy data at risk)
-- **Note**: MVP launches with fresh schema and no existing tenants. FU-701 adds `user_id` column and per-user RLS policies to tables that currently allow all authenticated users to see all records. Since there's no production data, this is building isolation from the start rather than migrating existing data.
-**Early Warning Signals:**
-- Test failures in multi-user isolation tests during FU-701 development
-- Policy logic errors causing users to see wrong data or no data
-- Service role queries failing (if policies too restrictive)
-- User reports of missing records or cross-tenant data leakage (post-launch)
-**Mitigation Strategy:**
-- FU-701 includes comprehensive testing with multi-tenant fixtures
-- Build `user_id` column and policies into schema from MVP start (not added later)
-- Test RLS policies thoroughly with multiple test users before launch
-- Verify service role can still perform background jobs (bypasses RLS correctly)
-- Database migration dry-runs in staging before production
-**Rollback Plan:**
-- Revert schema changes (drop `user_id` column, remove policies) - simple since no data exists
-- Temporarily revert to existing "public read" policy if needed
-- Fix policies and redeploy (low impact on empty system)
-- If users affected post-launch: Temporary workaround, notify affected users, fix within hours
-#### Failure Mode 2: Graph Integrity Regressions (Orphans/Cycles)
-- **Probability**: Medium (graph operations complex)
-- **Impact**: High (breaks core product assumptions)
-**Early Warning Signals:**
-- Integration tests fail with orphan/cycle detection
-- Graph integrity metrics show orphan_count > 0 or cycle_count > 0
-- User reports of missing records or timeline inconsistencies
-**Mitigation Strategy:**
-- FU-103 includes property-based tests for graph operations
-- Batch-level integration tests after each FU batch
-- Continuous monitoring of graph integrity metrics
-- Transactional inserts to maintain atomicity
-**Rollback Plan:**
-- Disable graph builder service immediately
-- Revert to single-record inserts (simpler, less risky)
-- Run graph repair scripts to fix orphans/cycles
-- Full audit of graph data before re-enabling batch inserts
-#### Failure Mode 3: MVP Date Slips by 2+ Weeks
-- **Probability**: High (11-14 week estimate aggressive for 8 FUs)
-- **Impact**: Medium (delays launch, extends costs)
-**Early Warning Signals:**
-- FU completion rate < 80% after 50% of batches complete (e.g., only 3/8 FUs done by Week 6)
-- Critical FUs (FU-100, FU-103) taking 2x estimated time
-- Integration test failures causing batch re-work
-- Discovery findings require significant scope changes
-**Mitigation Strategy:**
-- Mid-release checkpoint (Checkpoint 1) after Batch 1 to assess progress
-- Buffer time built into estimates (2-3 weeks per batch, not 1-2)
-- Identify P1/P2 features that can be descoped if needed
-- Continuous discovery reduces scope surprises
-**Rollback Plan** (Scope Reduction):
-- Move non-critical FUs to v1.1.0 (e.g., FU-105 if search can be basic)
-- Focus on P0-only subset for MVP
-- Adjust marketing timeline accordingly
-- Update target ship date transparently
-#### Failure Mode 4: OCR Determinism Fails in Production
-- **Probability**: Low (feasibility validation in discovery should catch this)
-- **Impact**: Critical (violates core product promise)
-**Early Warning Signals:**
-- Feasibility validation finds OCR non-deterministic edge cases
-- User reports of different extraction results on same document
-- Test suite shows flakiness in OCR output
-**Mitigation Strategy:**
-- Rigorous feasibility validation during discovery (100+ documents, 3x each)
-- Pin tesseract version explicitly (v5.3.0)
-- Test across different OS/environments
-- Low-confidence flagging catches non-deterministic cases
-**Rollback Plan:**
-- If discovered pre-launch: Pivot to different OCR engine or defer PDF support
-- If discovered post-launch: Mark affected records with warning, allow manual re-extraction
-- Communication: Transparent about determinism limitations
-- Long-term: Research alternative OCR solutions
-#### Failure Mode 5: Discovery Reveals Low Willingness-to-Pay (< €25/month)
-- **Probability**: Medium (pricing untested for this ICP)
-- **Impact**: High (threatens business model)
-**Early Warning Signals:**
-- Business viability discovery shows < 40% willing to pay ≥€25/month
-- Optimal price point (PSM intersection) < €25/month
-- Users express confusion about value proposition
-**Mitigation Strategy:**
-- Early price sensitivity testing in discovery (Van Westendorp method)
-- Clear value differentiation in discovery interviews
-- Test multiple price anchors (€10, €25, €50, €125)
-**Pivot Options:**
-- **Option A**: Freemium model (free tier + paid features)
-- **Option B**: Lower price point (€10-€15/month) with higher volume target
-- **Option C**: Usage-based pricing (per document or per query)
-- **Option D**: Defer monetization, focus on product-market fit first
-**Go/No-Go Decision:**
-- If < 30% willing to pay ≥€10/month → No-Go (defer MVP)
-- If 30-50% willing to pay → Pivot to freemium or lower price
-- If ≥50% willing to pay ≥€25/month → Go with planned pricing
-### 2. Pre-Mortem Action Items
-Before proceeding to discovery:
-1. **Discovery Phase**: Validate OCR determinism rigorously (Failure Mode 4)
-2. **Discovery Phase**: Test price sensitivity thoroughly (Failure Mode 5)
-3. **Development**: Build buffer time into FU estimates (Failure Mode 3)
-4. **FU-701**: Comprehensive RLS migration testing (Failure Mode 1)
-5. **FU-103**: Property-based graph integrity tests (Failure Mode 2)
-6. **Throughout**: Monitor early warning signals, adjust proactively
-### 3. Review and Adjustment
-Pre-mortem to be reviewed at:
-- **Checkpoint 0.5** (after discovery): Update based on discovery findings
-- **Checkpoint 1** (mid-release): Update based on execution progress
-- **Checkpoint 2** (pre-deployment): Final review before production
-### 4. Related Documents
-- `release_plan.md` — Release overview and scope
-- `deployment_strategy.md` — Deployment and rollback procedures
-- `acceptance_criteria.md` — Release-level acceptance criteria
-- `status.md` — Current status and progress tracking

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

@@ -1,160 +0,0 @@
-## Subscription Detection Strategy
-### Problem
-We need to identify users who pay for AI tools (ChatGPT Plus/Pro, Claude Pro, Cursor, Raycast) to prioritize high-commitment participants. However, subscription status is not directly observable through public APIs or profiles.
-### Detection Methods (Ranked by Reliability)
-#### 1. Self-Reported (Primary — Most Reliable)
-**Method**: Screening survey question
-**Question**: "Which AI tools do you currently pay for?" (Multiple choice: ChatGPT Plus/Pro, Claude Pro, Cursor, Raycast, Other, None)
-**Reliability**: ⭐⭐⭐⭐⭐ (100% accurate if answered honestly)
-**Advantages**:
-- Most accurate
-- Direct from user
-- No inference needed
-**Limitations**:
-- Requires user to complete survey
-- Some users may not answer honestly (social desirability bias)
-- Only available after initial outreach
-**When to Use**: Primary method in screening survey (Week -8)
-#### 2. Direct Mentions (Secondary — High Confidence)
-**Method**: Search bios, posts, profile descriptions for subscription mentions
-**Detectable Signals**:
-- Bio mentions: "ChatGPT Plus user", "Claude Pro subscriber", "Cursor Pro"
-- Post mentions: "I pay for ChatGPT Plus", "subscribed to Claude Pro"
-- Profile descriptions: Mentions of paid subscriptions
-**Filter Keywords**:
-- `ChatGPT Plus`, `ChatGPT Pro`, `Claude Pro`, `Cursor Pro`, `Raycast Pro`
-- `paid for ChatGPT`, `paid for Claude`, `subscribed to Cursor`
-- `ChatGPT subscriber`, `Claude subscriber`
-**Reliability**: ⭐⭐⭐⭐ (80-90% accurate — assumes users mention subscriptions)
-**Advantages**:
-- Detectable before outreach
-- Can filter leads proactively
-- Public signal
-**Limitations**:
-- Not all subscribers mention it publicly
-- Some mentions may be aspirational ("want ChatGPT Plus")
-- Requires parsing text (may have false positives)
-**When to Use**: Lead sourcing tools (Week -10 to -9), initial filtering
-**Implementation**: Add to Twitter/X, LinkedIn, GitHub search tools
-#### 3. Proxy Indicators (Tertiary — Supporting Evidence)
-**Method**: Infer paid access from usage patterns and feature mentions
-**Detectable Signals**:
-**Usage Frequency**:
-- Daily usage patterns suggest paid access (free tiers have rate limits)
-- High engagement with AI tools (posts, comments, shares)
-**Feature Mentions**:
-- ChatGPT Plus: Mentions of GPT-4, plugins, browsing, code interpreter
-- Claude Pro: Mentions of Claude 3 Opus, higher rate limits, longer context
-- Cursor: Mentions of AI completions, Pro features, code generation
-- Raycast: Mentions of AI features, Pro features
-**Activity Patterns**:
-- GitHub activity for Cursor users (Cursor integrates with GitHub)
-- High post frequency in AI tool communities (suggests heavy usage)
-- Multiple AI tool mentions (suggests paid access to multiple tools)
-**Reliability**: ⭐⭐⭐ (60-70% accurate — inference, not definitive)
-**Advantages**:
-- Detectable from public activity
-- Can identify heavy users even without explicit mentions
-**Limitations**:
-- Not definitive (free users can also be heavy users)
-- Requires inference logic
-- May have false positives/negatives
-**When to Use**: Supporting evidence, scoring boost, not primary filter
-**Implementation**: Scoring algorithm in unified lead manager
-#### 4. Direct Ask in Interview (Fallback)
-**Method**: Ask directly during interview if subscription status unclear
-**Question**: "Which AI tools do you currently pay for? This helps us understand your workflow."
-**Reliability**: ⭐⭐⭐⭐⭐ (100% accurate if answered honestly)
-**Advantages**:
-- Most accurate
-- Can clarify ambiguous signals
-- Natural conversation flow
-**Limitations**:
-- Only available after interview scheduled
-- Requires interview time
-**When to Use**: Fallback if subscription status unclear from other methods
-### Detection Workflow
-**Step 1: Lead Sourcing (Week -10 to -9)**
-- Search for direct mentions in bios/posts (Method 2)
-- Flag profiles with subscription signals
-- Score leads with subscription signals higher
-**Step 2: Screening Survey (Week -8) — Survey Path Only**
-- **For Survey Path**: Ask directly: "Which AI tools do you currently pay for?" (Method 1)
-- Primary detection method for survey path
-- Most reliable data
-- **For Direct Outreach Path**: Skip survey, use Methods 2-4 instead
-**Step 3: Lead Scoring**
-**For Survey Path:**
-- Combine self-reported data (Method 1) with detected signals (Method 2)
-- Add proxy indicators (Method 3) as supporting evidence
-- Score leads: High (self-reported + mentions), Medium (mentions only), Low (proxy only)
-**For Direct Outreach Path:**
-- Use detected signals (Method 2) + proxy indicators (Method 3)
-- Add brief screening question in calendar confirmation (Method 1, mini-survey)
-- Score leads: High (mentions + high usage), Medium (mentions only), Low (proxy only)
-**Step 4: Interview (Week -8 to -6)**
-- If subscription status unclear, ask directly (Method 4)
-- Verify self-reported data if needed
-### Scoring System
-**High Confidence (Score 0.9-1.0)**:
-- Self-reported in survey (Method 1) ✅
-- OR Direct mentions in bio/posts (Method 2) + High usage frequency (Method 3)
-**Medium Confidence (Score 0.7-0.9)**:
-- Direct mentions in bio/posts (Method 2) only
-- OR High usage frequency + Feature mentions (Method 3)
-**Low Confidence (Score 0.5-0.7)**:
-- Proxy indicators only (Method 3)
-- High usage frequency without explicit mentions
-**Unknown (Score <0.5)**:
-- No signals detected
-- Ask directly in interview (Method 4)
-### Implementation Recommendations
-**For Lead Sourcing Tools**:
-- Add subscription keyword search to Twitter/X, LinkedIn, GitHub tools
-- Flag profiles with subscription mentions for priority scoring
-- Note: This is supporting evidence, not definitive
-**For Screening Survey** (Survey Path Only):
-- Make subscription question required (primary detection method)
-- Ask early in survey (after basic qualification)
-- Use multiple choice for easy analysis
-**For Direct Outreach** (Direct Outreach Path):
-- Include brief screening question in calendar confirmation message
-- "Quick question: Which AI tools do you currently pay for? (ChatGPT Plus/Pro, Claude Pro, Cursor, None)"
-- Low friction (one question, optional but helpful)
-- Captures subscription status before interview
-**For Unified Lead Manager**:
-- Combine self-reported data (from survey) with detected signals (from tools)
-- Score leads: Self-reported > Mentions > Proxy indicators
-- Flag leads with subscription signals for priority outreach
-**For Interviews**:
-- If subscription status unclear, ask directly
-- Natural conversation flow: "Which AI tools do you pay for? This helps us understand your workflow."
-### Limitations and Assumptions
-**Limitations**:
-- No public API for subscription status
-- Self-reported data may have social desirability bias
-- Proxy indicators are inference, not definitive
-- Some users may not mention subscriptions publicly
-**Assumptions**:
-- Users who pay for tools are more likely to mention it (for Method 2)
-- Heavy usage correlates with paid access (for Method 3)
-- Self-reported data is accurate (for Method 1)
-**Mitigation**:
-- Use multiple detection methods (triangulation)
-- Prioritize self-reported data (most reliable)
-- Use proxy indicators as supporting evidence only
-- Ask directly in interview if unclear
-### Success Metrics
-**Detection Rate**:
-- Target: Identify 80%+ of paid subscribers through combined methods
-- Self-reported (Method 1): Expected 70-80% of subscribers
-- Direct mentions (Method 2): Expected 20-30% of subscribers
-- Proxy indicators (Method 3): Supporting evidence for 40-50%
-**Accuracy**:
-- Self-reported: 95%+ accurate (if answered honestly)
-- Direct mentions: 80-90% accurate (some false positives/negatives)
-- Proxy indicators: 60-70% accurate (inference, not definitive)
-**Priority Scoring**:
-- Leads with subscription signals (any method) score 0.7+
-- Leads with self-reported subscriptions score 0.9+
-- Leads without signals score <0.5 (lower priority)

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

@@ -1,115 +0,0 @@
-## Release v1.0.0 — Usability Discovery Plan
-### Purpose
-This document defines the usability discovery activities for v1.0.0, focused on validating that users can complete the upload → extraction → MCP query workflow without guidance and understand how to ask AI questions about their personal data.
-**Related Documents:**
-- `discovery_plan.md` — Discovery overview and coordination
-- `value_discovery_plan.md` — Value discovery activities
-- `business_viability_discovery_plan.md` — Business viability discovery activities
-- `participant_recruitment_log.md` — Participant tracking
-### 1. Hypothesis and Assumptions
-**Hypothesis:** "Users can complete upload → extraction → MCP query workflow without guidance, and understand how to ask AI questions about their personal data"
-**Assumptions:**
-- Upload UI is discoverable and intuitive
-- Users understand that uploaded documents become queryable via MCP
-- Users can successfully query their data via Claude/ChatGPT after setup
-- MCP setup/connection process is clear
-- Users understand what questions they can ask AI about their data
-### 2. Discovery Method
-**Method**: Prototype user testing (live, requires observation and think-aloud protocol)
-**Why Live Required:**
-- Must observe user behavior: Can't see confusion or errors in async survey
-- Think-aloud protocol: Users narrate actions, revealing mental model and confusion points
-- Dynamic probing: Ask follow-up questions based on observed behavior
-- Task completion requires observation: See where users get stuck
-### 3. Participants
-- **AI-Native Individual Operators**: 5 participants
-  - Recruitment: Subset from value discovery participants (those who validate problem and express interest)
-- **High-Context Knowledge Workers**: 3 participants
-  - Recruitment: Subset from value discovery participants
-**Total**: 8 participants
-### 4. Prototype Requirements
-- Clickable prototype (fully interactive)
-- Core workflows: Upload, view extracted data, MCP query simulation
-- Use existing design system
-- Mock MCP query interface (or actual Claude/ChatGPT with MCP connection)
-- No backend needed (except MCP simulation)
-### 5. Test Format
-- **Duration**: 45-60 minutes per session
-- **Protocol**: Think-aloud (users narrate actions)
-- **Recording**: Screen and audio recording
-- **Approach**: Task-based testing (give users goals, observe)
-### 6. Testing Scenarios
-#### Scenario 1: Upload and View Extracted Data
-**Duration**: 10 min
-**Description**: "Imagine you just signed up for Neotoma. You want to upload a contract PDF so that Claude can answer questions about it later. Please do that and see what information Neotoma extracted."
-**Observe:**
-- Can user find upload UI?
-- Can user complete upload?
-- Does user understand what was extracted?
-- Does user understand this data is now queryable by AI?
-**Success**: User completes upload, views extracted data, understands it's AI-accessible
-#### Scenario 2: Query Personal Data via AI (MCP Simulation)
-**Duration**: 15 min
-**Description**: "Now you want to ask Claude a question about your uploaded contract. Try asking: 'What's the contract value?' or 'When does this contract expire?' (We'll simulate MCP query or use actual Claude with MCP connection)"
-**Observe:**
-- Can user understand how to query via AI? (MCP concept)
-- Can user successfully ask questions?
-- Does user understand AI is accessing their uploaded data?
-- Are the AI answers clear and helpful?
-- Time to successful query
-**Success**: User successfully queries personal data via AI within reasonable time, understands MCP workflow
-#### Scenario 3: Ask Multiple Questions Across Documents
-**Duration**: 10 min
-**Description**: "You've uploaded multiple documents (contract, receipt, travel booking). Try asking Claude: 'Show me all my travel bookings next month' or 'What companies have I interacted with?'"
-**Observe:**
-- Can user ask cross-document questions?
-- Does user understand AI can query multiple documents?
-- Are answers accurate and helpful?
-**Success**: User successfully asks cross-document questions, AI provides useful answers
-#### Scenario 4: Timeline Discovery
-**Duration**: 10 min
-**Description**: "Neotoma also creates a timeline view of events from your documents. Can you find the timeline and see your documents organized chronologically?"
-**Observe:**
-- Can user find timeline view?
-- Does user understand timeline organization?
-- Does user see value in chronological view?
-**Success**: User navigates to timeline and understands chronological organization
-#### Scenario 5: Post-Test Questions
-**Duration**: 10 min
-**Description**: Gather overall usability feedback
-**Questions:**
-1. "Overall, how easy was this to use? (1-5 scale)"
-2. "Does the MCP query workflow make sense to you?"
-3. "What was confusing about querying your data via AI?"
-4. "What worked well?"
-5. "Would you use this? Why or why not?"
-6. "What questions would you want to ask AI about your personal data?"
-### 7. Success Criteria
-- ≥80% complete Scenario 1 (Upload) without help
-- ≥70% complete Scenario 2 (MCP Query) successfully within reasonable time
-- ≥65% successfully ask cross-document questions (Scenario 3)
-- ≥70% navigate to timeline (Scenario 4) without prompting
-- ≥70% understand that uploaded data becomes queryable via AI
-- System Usability Scale (SUS) score ≥70
-- ≤2 critical usability blockers identified
-### 8. Timeline
-**Timeline**: Week -7 to Week -6
-**Schedule:**
-- Week -7: Prepare prototype, schedule participants (subset from value discovery)
-- Week -7 to -6: Conduct usability testing sessions (8 participants)
-- Week -6: Synthesize findings
-### 9. Deliverable
-**Deliverable**: `usability_discovery_report.md`
-Includes:
-- Task completion rates for each scenario
-- Usability issues identified (critical blockers, minor friction)
-- SUS score and analysis
-- User mental model insights
-- Recommendations for UI improvements
-- Comparison against success criteria
-### 10. Related Documents
-- `discovery_plan.md` — Discovery overview and coordination
-- `value_discovery_plan.md` — Value discovery activities
-- `business_viability_discovery_plan.md` — Business viability discovery activities
-- `participant_recruitment_log.md` — Participant tracking
-- `docs/feature_units/standards/discovery_process.md` — Discovery process standard