Navigator v5.0.0 - Theory of Mind

Navigator v5.0.0 - Theory of Mind

Release Date: 2025-12-11

Overview

Navigator v5.0.0 introduces Theory of Mind (ToM) features for better human-AI collaboration. Based on Riedl & Weidmann 2025 research showing 23-29% performance boost from ToM alignment.

Two-Layer Architecture

Navigator = Context Engineering + Human-AI Collaboration

Layer 1: Context Efficiency (v1-v4)
├── 92% token savings (verified via OpenTelemetry)
├── Lazy loading documentation
├── Context markers (97% compression)
├── Agent-optimized search
└── Proven, stable foundation

Layer 2: Theory of Mind (v5.0.0) [NEW]
├── Bilateral modeling (nav-profile)
├── Quality detection (nav-diagnose)
├── Verification checkpoints
├── Auto-learn corrections
└── Intent capture in markers

New Features

1. nav-profile Skill

Purpose: Claude learns your preferences across sessions

How it works:

"Remember I prefer concise explanations"
→ Saved to .agent/.user-profile.json
→ Applied in future sessions
→ Survives context clears and compacts

Features:

• Communication preferences (verbosity, confirmation threshold)
• Technical preferences (frameworks, code style)
• Workflow preferences (autonomous commits, compact threshold)
• Auto-learn from corrections (silent capture)
• Goal tracking across sessions

Commands:

• "Save my preferences" → Creates/updates profile
• "Show my profile" → Displays current settings
• "Reset my profile" → Clears all preferences

2. nav-diagnose Skill

Purpose: Detects when collaboration quality drops and prompts re-anchoring

Triggers:

• Same correction given twice
• User says "you're not getting this", "wrong again"
• Context confusion detected
• Frustration signals ("ugh", "sigh")

Output:

⚠️  QUALITY CHECK
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Detected Issue: Repeated Corrections
Severity: High

What I noticed:
- Same naming convention correction twice
- REST endpoint plural naming

Let me re-anchor:
1. Your goal: Create user API endpoints
2. Current state: 3/5 endpoints complete
3. Rule established: Use plural nouns (/users not /user)

Is this understanding correct? [Y/n]

3. Verification Checkpoints

Purpose: Confirm understanding before generating high-stakes code

Skills with checkpoints:

• backend-endpoint - Verifies endpoint design before generation
• frontend-component - Confirms component structure
• database-migration - ALWAYS verifies (database changes are critical)
• nav-task - Verifies interpretation when archiving tasks

Checkpoint format:

I understood you want:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Endpoint: POST /api/users
Framework: Express (detected from package.json)
Auth required: yes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Assumptions I'm making:
- Using Joi for validation (detected from existing validators)
- Error handling follows existing pattern in src/middleware/error.ts

Proceed with generation? [Y/n]

Skip conditions (HIGH-STAKES ONLY mode):

• Simple CRUD operations
• User explicitly says "quick" or "skip confirmation"
• Standard patterns with no customization

4. Auto-Learn Corrections

Purpose: Silently learn from user corrections to avoid repeating mistakes

Detection patterns:

• "No, I meant..." → Direct correction
• "Actually, ..." → Clarification
• "Not X, use Y" → Substitution
• "Always use ..." → Rule establishment
• "Never do ..." → Anti-pattern

Storage:

• Saved to .agent/.user-profile.json
• Rolling window (last 20 corrections)
• Persists across sessions

Feedback (every 5 corrections):

📚 I've learned from your corrections:
- REST endpoints should use plural nouns
- You prefer functional components over class components
- TypeScript strict mode is required

These will be applied in future sessions.

5. Enhanced Context Markers

Purpose: Capture user intent and corrections, not just technical state

New sections in markers:

## User Intent & Goals (ToM) [CAPTURE ACTIVELY]

**Primary goal this session**:
Implement OAuth for user authentication

**Stated preferences**:
- Prefers concise explanations
- Wants functional components

**Corrections made**:
- "Should be /users not /user (plural convention)"
- "Use httpOnly cookies for tokens"

## Belief State [CAPTURE ACTIVELY]

**What user knows**:
- Familiar with Express, new to Passport
- Senior developer, skip basics

**Assumptions I made**:
- Using Redis for sessions (confirmed)
- Auth endpoints at /api/auth/*

Configuration

New ToM configuration in .agent/.nav-config.json:

{
  "version": "5.0.0",
  "tom_features": {
    "verification_checkpoints": true,
    "confirmation_threshold": "high-stakes",
    "profile_enabled": true,
    "diagnose_enabled": true,
    "belief_anchors": false
  }
}

Options:

• verification_checkpoints: Enable/disable checkpoints (default: true)
• confirmation_threshold: "always" | "high-stakes" | "never" (default: "high-stakes")
• profile_enabled: Enable nav-profile skill (default: true)
• diagnose_enabled: Enable nav-diagnose skill (default: true)
• belief_anchors: Optional explicit assumption declarations (default: false)

Navigator + Claude Code

Claude Code v2.0.107 has features that appear similar but serve different purposes:

Use both: Claude Code handles infrastructure, Navigator handles strategy + collaboration.

Migration from v4.x

Automatic:

• Existing .agent/ structure preserved
• Skills continue working
• No breaking changes

New files created on first use:

• .agent/.user-profile.json (when preferences saved)
• Enhanced markers (ToM sections added automatically)

Configuration update:

# Check current version
cat .agent/.nav-config.json | grep version

# Update to v5.0.0 (preserves other settings)
# nav-upgrade skill handles this automatically

Research Foundation

Theory of Mind features based on:

Riedl & Weidmann 2025 - "Humans are not tokens: Interindividual differences and the human-AI synergy"

Key findings:

• ToM predicts 23-29% collaborative performance boost
• ToM varies dynamically within users (moment-to-moment)
• Bilateral modeling (both human→AI and AI→human) matters

Navigator implementation:

• nav-profile: AI→human modeling (Claude learns you)
• nav-diagnose: Detects when ToM alignment degrades
• Checkpoints: Explicit verification of mutual understanding

Skills Updated

Known Limitations

1. Auto-learn requires explicit corrections - Implicit preferences harder to detect
2. Checkpoints add friction - Configurable via confirmation_threshold
3. Profile is local - Not synced across machines (git-ignored)

Upgrade Path

# 1. Update plugin
/plugin update navigator

# 2. Run upgrade skill (optional, updates CLAUDE.md)
"Upgrade Navigator to latest version"

# 3. Start session - profile loading automatic
"Start my Navigator session"

Changelog

v5.0.0 (2025-12-11)

• NEW: nav-profile skill for bilateral modeling
• NEW: nav-diagnose skill for quality detection
• NEW: Verification checkpoints in high-stakes skills
• NEW: Auto-learn correction detection
• ENHANCED: nav-marker with intent/belief state capture
• ENHANCED: nav-start with profile loading
• ADDED: "Navigator + Claude Code" comparison section

Navigator v5.0.0: Context efficiency remains the foundation. Theory of Mind makes collaboration better.