Peekaboo MCP

# Intelligent Build Prioritization <!-- Generated: 2025-08-02 22:18:00 UTC --> ## Overview Poltergeist's Intelligent Build Prioritization automatically determines which targets to build first based on your development patterns. Instead of building targets in random order, the system learns from your behavior and prioritizes the targets you're actively working on. ## How It Works ### Core Concept When you make changes that affect multiple targets, Poltergeist analyzes: - **Recent Focus Patterns** - Which targets you've been changing most frequently - **Change Types** - Direct target changes vs shared dependency changes - **Build Performance** - Success rates and build times - **Development Context** - Current session activity patterns The system then builds the most relevant target first, minimizing waiting time for the code you're actually working on. ### Example Scenarios **Scenario 1: Mac App Development** ``` You make 5 changes to Mac app files over 2 minutes Then you change a shared Core file Result: Mac app builds first (high recent focus) CLI builds second (affected by Core change) ``` **Scenario 2: Context Switching** ``` You change a CLI file Immediately change a Mac app file Immediately change CLI file again Result: CLI builds first (most recent direct changes) Mac app builds after CLI completes ``` **Scenario 3: Serial Build Mode** ``` parallelization = 1 (serial builds only) You change both CLI and Mac files simultaneously Result: System picks target with higher priority score Other target queues for build after completion ``` ## Configuration ### Basic Setup Add to your `poltergeist.config.json`: ```json { "buildScheduling": { "parallelization": 1, "prioritization": { "enabled": true, "focusDetectionWindow": 600000, "priorityDecayTime": 1800000 } } } ``` ### Configuration Options #### `parallelization` (number) - **Default**: `2` - **Description**: Maximum number of concurrent builds - **Values**: - `1` = Serial builds (one at a time) - `2+` = Parallel builds (multiple simultaneous) #### `prioritization.enabled` (boolean) - **Default**: `true` - **Description**: Enable intelligent prioritization - **Note**: When disabled, targets build in configuration order #### `prioritization.focusDetectionWindow` (milliseconds) - **Default**: `600000` (10 minutes) - **Description**: Time window for detecting user focus patterns - **Range**: `60000` - `3600000` (1 minute to 1 hour) #### `prioritization.priorityDecayTime` (milliseconds) - **Default**: `1800000` (30 minutes) - **Description**: How long elevated priorities persist - **Range**: `300000` - `7200000` (5 minutes to 2 hours) ## Priority Scoring Algorithm ### Base Score Calculation Each target receives a dynamic priority score based on: 1. **Direct Changes** (100 points each) - Files that belong exclusively to the target - Recent changes weighted more heavily 2. **Change Frequency** (50 points per change) - Number of recent changes to target files - Calculated within focus detection window 3. **Focus Multiplier** (1x - 2x) - Strong focus (80%+ recent changes): 2x multiplier - Moderate focus (50-80%): 1.5x multiplier - Weak focus (30-50%): 1.2x multiplier - No focus (<30%): 1x multiplier 4. **Build Success Rate** (0.5x - 1x) - Targets that build successfully get higher priority - Failing targets get reduced priority to avoid blocking 5. **Build Time Penalty** (0.8x in serial mode) - Slow builds (>30 seconds) get reduced priority when parallelization=1 - Prevents long builds from blocking faster ones ### Priority Score Formula ``` score = directChanges * 100 + changeFrequency * 50 score *= focusMultiplier score *= (0.5 + successRate * 0.5) if (parallelization === 1 && avgBuildTime > 30s) { score *= 0.8 } ``` ## Build Queue Management ### Intelligent Queuing Features - **Priority Queue**: Always builds highest-priority target first - **Build Deduplication**: Prevents multiple builds of same target - **Dynamic Re-prioritization**: Updates priorities when new changes arrive - **Build Cancellation**: Cancels queued low-priority builds for urgent changes - **Change Batching**: Groups rapid changes into single build ### Queue Behavior When files change that affect multiple targets: 1. **Calculate Priorities**: Each affected target gets scored 2. **Check Running Builds**: If target already building, mark for rebuild 3. **Update Queue**: Add/update build requests by priority 4. **Process Queue**: Start builds respecting parallelization limit 5. **Monitor Changes**: Re-evaluate priorities on new file changes ## File Change Classification ### Change Types **Direct Changes** - Files that belong exclusively to one target - Examples: `Apps/CLI/main.swift`, `Apps/Mac/AppDelegate.swift` - **Weight**: High priority impact **Shared Changes** - Files that affect multiple targets - Examples: `Core/PeekabooCore/*.swift`, shared libraries - **Weight**: Distributed across affected targets **Generated Changes** - Auto-generated files (like `Version.swift`) - **Weight**: Lower priority, often batched ### Impact Analysis The system analyzes each file change to determine: - Which targets are affected - The relative impact weight - Whether it's a user change or generated change - The appropriate priority adjustment ## Development Workflows ### Recommended Settings **Solo Development** ```json { "buildScheduling": { "parallelization": 1, "prioritization": { "enabled": true } } } ``` *Focus on one target at a time for faster feedback* **Multi-Target Development** ```json { "buildScheduling": { "parallelization": 2, "prioritization": { "enabled": true } } } ``` *Balance parallel builds with intelligent prioritization* **Team Development** ```json { "buildScheduling": { "parallelization": 3, "prioritization": { "enabled": true, "focusDetectionWindow": 300000 } } } ``` *Shorter focus window for faster context switching* ### Usage Patterns **Pattern 1: Deep Focus** - Work on single target for extended periods - System learns your focus and prioritizes that target - Shared dependency changes build your target first **Pattern 2: Context Switching** - Rapid switching between targets - System adapts to your most recent activity - Prioritizes target with most recent direct changes **Pattern 3: Shared Library Work** - Changes affect multiple targets - System prioritizes based on recent focus patterns - Falls back to configuration order if no clear focus ## Monitoring and Debugging ### Status Information Check current priorities: ```bash npm run poltergeist:status ``` View priority details in state files: ```bash cat /tmp/poltergeist/*.state | jq '.priority' ``` ### Debug Logging Enable detailed priority logging: ```json { "logging": { "level": "debug", "categories": ["priority", "queue"] } } ``` ### Common Issues **Problem**: Wrong target builds first - **Cause**: Insufficient focus detection data - **Solution**: Continue working; system learns your patterns **Problem**: Builds feel slow - **Cause**: parallelization=1 with large targets - **Solution**: Increase parallelization or optimize build times **Problem**: Builds seem random - **Cause**: No clear focus pattern detected - **Solution**: Focus on fewer targets or disable prioritization ## Performance Impact ### Benefits - **Reduced Wait Time**: Build the target you need first - **Better Resource Usage**: Avoid unnecessary parallel builds - **Adaptive Behavior**: System improves over time - **Intelligent Batching**: Groups related changes efficiently ### Overhead - **Memory**: ~10MB for tracking change history and priorities - **CPU**: <1% overhead for priority calculations - **Disk**: Additional state tracking in `/tmp/poltergeist/` ### Benchmarks With intelligent prioritization enabled: - **Focus Accuracy**: 85-95% builds correct target first - **Build Efficiency**: 20-40% reduction in unnecessary builds - **Developer Latency**: 30-50% reduction in wait time for relevant builds ## Advanced Features ### Future Enhancements **Machine Learning Integration** - Learn individual developer preferences - Predictive building based on patterns - Team-wide pattern recognition **IDE Integration** - Detect which files are open/focused - Integration with editor activity - Smart build triggers based on editor events **Test-Driven Prioritization** - Prioritize targets with failing tests - Build dependencies before dependents - Smart test target selection ### Extension Points The prioritization system is designed to be extensible: - Custom priority calculators - External priority data sources - Plugin-based heuristics - API-driven priority adjustments ## Troubleshooting ### Disabling Prioritization To disable and use simple queue ordering: ```json { "buildScheduling": { "prioritization": { "enabled": false } } } ``` ### Resetting Priority History Clear learned patterns: ```bash rm /tmp/poltergeist/priority-history.json npm run poltergeist:restart ``` ### Manual Priority Override For testing or special cases: ```bash # Force CLI to build first (development feature) echo '{"peekaboo-cli": 1000}' > /tmp/poltergeist/priority-override.json ``` ## Implementation Status > **Note**: This feature is currently in design phase and not yet implemented. > This documentation describes the planned behavior and configuration options. > > **Tracking**: See [GitHub Issue #XXX](link-to-issue) for implementation progress. ## References - [Poltergeist Configuration Guide](./poltergeist-configuration.md) - [Build System Architecture](./build-system.md) - [Performance Optimization](./performance-optimization.md)