Performance & Reliability Critical Path

[prosdev]

Critical High-Impact Performance & Reliability Improvements

This ticket addresses blocking user experience issues and performance bottlenecks that prevent widespread adoption.

P0 - Blocking User Experience

1. MCP Server Lazy Initialization 🚨

• Issue: Eager initialization causes 2-5s delays in AI tools
• Location: packages/mcp-server/bin/dev-agent-mcp.ts:117
• Impact: Every AI interaction blocked by full indexer startup
• Fix: Initialize only on first tool call, not server start
• Success Criteria: <500ms MCP server startup (currently 2-5s)

2. Missing Index Size Reporting 💾

• Issue: Users can't track disk usage growth
• Location: packages/cli/src/commands/index.ts:151
• Impact: Enterprise adoption blocker, no storage planning
• Fix: Calculate and report actual vector store sizes
• Success Criteria: Show disk usage in dev stats

3. Broken GitHub History Integration 🔗

• Issue: Planner missing critical commit context
• Location: packages/mcp-server/src/adapters/built-in/plan-adapter.ts:173
• Impact: AI plans lack historical context, poor quality
• Fix: Enable includeHistory: true with proper error handling
• Success Criteria: Planner includes related commits

P1 - Performance & Scalability

4. Indexing Performance Configuration ⚡

• Issue: No adaptive batching for repository size
• Current: Fixed 32 batch size regardless of repo complexity
• Impact: Large repos (>10k files) extremely slow, small repos waste memory
• Fix: Auto-detect optimal batch size based on file count/system resources
• Success Criteria: <5min for 50k files (currently 15-30min)

5. Memory Leak Prevention 🧠

• Issue: No monitoring for long-running MCP processes
• Location: Circular buffers exist but no usage tracking
• Impact: AI tools become unresponsive after heavy use
• Fix: Add memory monitoring with automatic restart thresholds
• Success Criteria: <500MB steady state memory usage

6. Incremental Indexing Gaps 🔄

• Issue: Full re-index required for any change
• Impact: 5+ minute delays on large codebases for minor updates
• Fix: File-level change detection with vector store deltas
• Success Criteria: <30s updates for single file changes

P2 - User Experience Blockers

7. Error Message Quality 💬

• Issue: Technical errors exposed to end users
• Example: "VectorStorage not initialized" → "Repository not indexed"
• Impact: User abandonment during setup
• Fix: User-friendly error translation layer
• Success Criteria: 90% self-healing without user intervention

8. Setup Validation ✅

• Issue: No pre-flight checks for common failures
• Missing: Node version, disk space, git repo validation
• Impact: Silent failures, difficult debugging
• Fix: Comprehensive setup validation with actionable guidance
• Success Criteria: Clear validation errors with solutions

9. Progress Indicators 📊

• Issue: Black box indexing with no feedback
• Impact: Users assume tool is broken during long operations
• Fix: Real-time progress with ETA estimates
• Success Criteria: Progress bars for all long operations

Implementation Priority

1. MCP lazy init - Immediate UX win, low risk
2. GitHub history fix - High value, well-defined scope
3. Index size reporting - Enterprise requirement, simple fix
4. Adaptive batching - Major performance gain
5. Error message layer - Reduces support burden
6. Progress indicators - UX polish

Success Metrics

• MCP server startup: <500ms (currently 2-5s)
• Large repo indexing: <5min for 50k files (currently 15-30min)
• Memory usage: <500MB steady state (currently unbounded growth)
• Error recovery: 90% self-healing without user intervention

---

Focus: Shipping blockers that prevent widespread adoption, not nice-to-have features. Each item addresses real user pain points with clear success criteria.

[prosdev]

Sub-issue created: #122 - Incremental indexing via rebuild strategy

[prosdev]

Remaining Work

Created 3 focused issues for remaining P0/P1 items:

• feat(mcp): Implement lazy initialization for MCP server #152 - MCP Lazy Initialization (P0) - 2-5s startup delay
• feat(mcp): Enable GitHub history integration in planner #153 - GitHub History Integration (P0) - Missing commit context
• feat(mcp): Add memory monitoring for long-running processes #154 - Memory Monitoring (P1) - Production stability

Completed items (6/9):

• ✅ Epic: Subagent Foundation #2 - Index size reporting (v0.4.3)
• ✅ Implement Vector Storage with LanceDB and Transformers.js #4 - Adaptive concurrency (v0.6.0)
• ✅ Implement CLI and Integration Examples #6 - Incremental indexing (v0.5.1, feat(core): Incremental indexing via rebuild strategy #122)
• ✅ Implement Explorer Subagent #9 - Progress indicators (v0.1.0)
• ✅ Error handling improvements
• ✅ Basic validation

Once #152-154 are complete, this epic can be closed.