---
summary: 'Review Intelligent Build Prioritization guidance'
read_when:
  - 'planning work related to intelligent build prioritization'
  - 'debugging or extending features described here'
---

# 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)