093 2026 01 29 032608ee

# Session Learnings - 2026-01-29

Automatically captured from Claude Code sessions.

---

## [09:45] - Onboarding: Email domain step was skipped

**What happened:** During onboarding test, Step 3.5 (email domain collection) was not executed, breaking the Internal/External person routing feature.

**Why it matters:** Without email domain, the system cannot automatically route people to Internal/ or External/ folders, and company pages won't be created for external organizations.

**Implemented fix:** Created onboarding MCP server for bulletproof validation
1. Renumber Step 3.5 to Step 4 (full number, not decimal) ✅
2. Add warning banner: "⚠️ DO NOT SKIP THIS STEP" ✅
3. Created `core/mcp/onboarding_server.py` with stateful validation ✅
4. Session management with resume capability ✅
5. Email domain validation (format check: no @, must have dot, supports multiple domains) ✅
6. Dependency verification (Python packages, Calendar.app, Granola) ✅
7. Automatic MCP configuration with VAULT_PATH substitution ✅
8. Updated onboarding flow to use MCP tools at each step ✅
9. Updated CLAUDE.md, README.md, CHANGELOG.md, Technical Guide ✅
10. Validated with automated tests (9/9 email tests, 5/5 pillar tests passed) ✅

**Status:** completed

---

## [15:30] - Phase 2 Onboarding System - Complete Implementation

**What was built:** Comprehensive post-onboarding experience that adapts to available data sources

**Why it matters:** Transforms "I have a system, now what?" into immediate value. No blank chat window anxiety.

**Implementation:**

1. **Onboarding MCP enhancements:**
   - Marker file (`.onboarding-complete`) tracks completion + vault age
   - `check_onboarding_complete` tool for Phase 2 detection
   - 7-day lookback window enforced

2. **Session start hook:**
   - Detects new vaults (< 7 days old)
   - Suggests `/getting-started` if Phase 2 not completed
   - Non-intrusive reminder

3. **Onboarding flow Step 10:**
   - Offers Phase 2 tour immediately after core setup
   - Can skip and come back later
   - Clear value proposition4. **/getting-started skill - Adaptive pathways:**
   - **Flow A (Calendar + Granola):** "I already looked" - analyzes what's there, offers to process
   - **Flow B (One or other):** "Complete the picture" - help connect missing piece
   - **Flow C (Neither):** "Connect your tools" - wizard to build integrations
   - Includes: tool integration, Google Workspace setup, information diet, Cursor UX tips
   - 7-day default, asks before going back further
   - Ask before creating (people pages, company pages, tasks)
   - External contacts → External/ folder verified

5. **/integrate-mcp skill:**
   - Points to Smithery.ai marketplace
   - Accepts MCP URLs
   - Fetches + analyzes documentation
   - Guides configuration
   - Tests connections
   - Updates Dex docs

6. **Key philosophy:**
   - Adaptive magic based on available data
   - "Show, don't tell" when data exists
   - Educational even when things fail
   - Low pressure, clear escapes everywhere
   - Context now → rhythm later

**Status:** completed

---

## [16:00] - Phase 2 Magic Complete - Pre-Analysis Implementation

**What was built:** The final 15% - proactive "surprise and delight" pre-analysis during onboarding

**Why it matters:** Transforms onboarding from "here's your empty system" to "I already analyzed your world and created things for you"

**Implementation:**

1. **Pre-analysis helper functions** (`onboarding_server.py`):
   - `get_calendar_events_for_week()` - Dynamic import of calendar MCP
   - `analyze_calendar_events()` - Extract meetings, 1:1s, busiest day, top people
   - `generate_weekly_plan()` - Create markdown plan with real meeting data
   - `write_weekly_plan()` - Write to `02-Week_Priorities/Week_Priorities.md`
   - `get_frequent_attendees()` - Find top N contacts by meeting frequency
   - `create_person_page()` - Auto-route to Internal/External based on domain
   - `get_recent_granola_meetings()` - Dynamic import of Granola MCP
   - `count_unique_people()` - Deduplicate attendees across meetings
   - `count_external_companies()` - Find external orgs by domain

2. **Pre-analysis during finalization** (step 6.5):
   - Runs silently after MCP config setup
   - Tries calendar analysis → creates weekly plan + person pages
   - Tries Granola analysis → counts meetings/people/companies
   - Graceful failure - errors don't block onboarding
   - Results stored in `pre_analysis` object

3. **Marker file enhancement**:
   - Added `pre_analysis` field with all insights
   - Includes: calendar stats, created_weekly_plan flag, created_person_pages count, person_names, Granola stats
   - Available for Phase 2 to avoid duplicate work

4. **Dramatic reveal in Step 9** (onboarding.md):
   - **With data:** Shows real insights (meeting count, 1:1s, busiest day, top contacts)
   - Reveals: "I went ahead and created your weekly plan"
   - Shows actual file excerpt
   - Message: "This is what Dex does - it works while you're not looking"
   - **Without data:** Falls back to standard completion (don't overpromise)

5. **`/getting-started` enhancement**:
   - Checks marker file for existing pre_analysis
   - **If exists:** "I already analyzed your data during setup. Here's what's new since then..."
   - **If not:** Runs full analysis from scratch (legacy/failed cases)
   - Prevents duplicate work and acknowledges existing artifacts

**Key design decisions:**
- Pre-analysis is opportunistic, not required - failures don't block onboarding
- Only creates artifacts if data actually exists
- Respects 7-day window for Granola
- Proper Internal/External routing based on email domain
- Returns pre_analysis in finalize response for immediate reveal

**Testing checklist:**
- [ ] Test with calendar + Granola (full magic)
- [ ] Test with calendar only (partial magic)
- [ ] Test with Granola only (partial magic)
- [ ] Test with neither (graceful fallback)
- [ ] Test failure scenarios (MCP errors don't break onboarding)
- [ ] Verify person pages route correctly to Internal/External
- [ ] Verify weekly plan has real meeting data
- [ ] Verify `/getting-started` acknowledges existing work

**Status:** completed (implementation), pending (user testing)

---

## [17:00] - Architecture Fix: Pre-Analysis Timing

**What was wrong:** Pre-analysis was trying to run during onboarding finalization, but MCPs weren't loaded yet (chicken-and-egg problem).

**Why it mattered:** Users got boring completion message instead of dramatic reveal with real insights.

**Root cause:** `.mcp.json` is created during finalization, but Claude doesn't load MCPs until next turn.

**The fix - Graceful UX flow:**

1. **Onboarding Step 9:** Clear bridge to Phase 2
   - "I'm going to analyze your calendar and meetings..."
   - "Want me to run the getting started tour?"
   - Sets expectations, no technical jargon

2. **User says "yes"** → Invoke `/getting-started` skill

3. **New conversation turn** → MCPs are loaded

4. **`/getting-started` runs pre-analysis:**
   - Checks for `pre_analysis_deferred: true` flag
   - Checks if < 1 hour since onboarding
   - Runs full calendar + Granola analysis
   - Creates weekly plan with real meeting data
   - Creates person pages for top 3 contacts
   - Shows dramatic reveal

5. **Dramatic reveal:**
   - "Here's what I found: [X] meetings, [Y] 1:1s..."
   - "I went ahead and created: weekly plan, person pages..."
   - Shows actual file excerpt
   - "This is what Dex does"

**Key insight:** The "new turn" when `/getting-started` runs IS the MCP reload. No need to ask user to do anything technical.

**Status:** completed

---