# Orchestrator Learnings (Universal)

> Cross-project heuristic adjustments based on observed variance data.
>
> **Note:** This file contains generic patterns only. Project-specific evidence is stored in each project's `docs/tasks/orchestrator-learnings.json`.

## Task Type Multipliers

Apply these multipliers to base estimates from `ORCHESTRATOR.md`:

| Task Type | Base Estimate | Multiplier | Confidence | Samples | Last Updated |
|-----------|---------------|------------|------------|---------|--------------|
| STYLE_FIX | 3-5K | 0.64 | MEDIUM | n=1 | 2026-02-05 |
| BULK_CLEANUP | file_count × 550 | 1.0 | MEDIUM | n=2 | 2026-02-05 |
| GUARD_ADD | 5-8K | 1.0 | LOW | n=0 | - |
| SECURITY_FIX | 8-12K | 2.5 | LOW | n=0 | - |
| AUTH_ADD | 15-25K | 1.0 | HIGH | n=1 | 2026-02-05 |
| REFACTOR | 10-15K | 1.0 | LOW | n=0 | - |
| TEST_ADD | 15-25K | 1.0 | LOW | n=0 | - |
| ERROR_HANDLING | 8-12K | 2.3 | MEDIUM | n=1 | 2026-02-05 |
| CONFIG_DEFAULT_CHANGE | 5-10K | 1.8 | MEDIUM | n=1 | 2026-02-05 |
| INPUT_VALIDATION | 5-8K | 1.7 | MEDIUM | n=1 | 2026-02-05 |

## Phase Factors

Apply to all estimates based on task position in milestone:

| Phase Position | Factor | Rationale |
|----------------|--------|-----------|
| Early (tasks 1-3) | 1.45 | Codebase learning overhead |
| Mid (tasks 4-7) | 1.25 | Pattern recognition phase |
| Late (tasks 8+) | 1.10 | Established patterns |

## Estimation Formula

```
Final Estimate = Base Estimate × Type Multiplier × Phase Factor × TDD Overhead

Where:
- Base Estimate: From ORCHESTRATOR.md task type table
- Type Multiplier: From table above (default 1.0)
- Phase Factor: 1.45 / 1.25 / 1.10 based on position
- TDD Overhead: 1.20 if tests required
```

## Known Patterns

### BULK_CLEANUP

**Pattern:** Multi-file cleanup tasks are severely underestimated.

**Why:** Iterative testing across many files, cascading fixes, and debugging compound the effort.

**Observed:** +112% to +276% variance when using fixed estimates.

**Recommendation:** Use `file_count × 550` instead of fixed estimate.

### ERROR_HANDLING

**Pattern:** Error handling changes that modify type interfaces cascade through the codebase.

**Why:** Adding fields to result types requires updating all callers, error messages, and tests.

**Observed:** +131% variance.

**Multiplier:** 2.3x base estimate when type interfaces are modified.

### CONFIG_DEFAULT_CHANGE

**Pattern:** Config default changes require more test coverage than expected.

**Why:** Security-sensitive defaults need validation tests, warning tests, and edge case coverage.

**Observed:** +80% variance.

**Multiplier:** 1.8x when config changes need security validation.

### INPUT_VALIDATION

**Pattern:** Security input validation with allowlists is more complex than simple validation.

**Why:** Comprehensive allowlists (e.g., OAuth error codes), encoding requirements, and security tests add up.

**Observed:** +70% variance.

**Multiplier:** 1.7x when security allowlists are involved.

### STYLE_FIX

**Pattern:** Pure formatting fixes are faster than estimated when isolated.

**Observed:** -36% variance.

**Multiplier:** 0.64x for isolated style-only fixes.

## Changelog

| Date | Change | Samples | Confidence |
|------|--------|---------|------------|
| 2026-02-05 | Added BULK_CLEANUP category | n=2 | MEDIUM |
| 2026-02-05 | Added STYLE_FIX multiplier 0.64 | n=1 | MEDIUM |
| 2026-02-05 | Confirmed AUTH_ADD heuristic accurate | n=1 | HIGH |
| 2026-02-05 | Added ERROR_HANDLING multiplier 2.3x | n=1 | MEDIUM |
| 2026-02-05 | Added CONFIG_DEFAULT_CHANGE multiplier 1.8x | n=1 | MEDIUM |
| 2026-02-05 | Added INPUT_VALIDATION multiplier 1.7x | n=1 | MEDIUM |

## Update Protocol

**Graduated Autonomy:**

| Phase | Condition | Action |
|-------|-----------|--------|
| **Now** | All proposals | Human review required |
| **After 3 milestones** | <30% change, n≥3 samples, HIGH confidence | Auto-update allowed |
| **Mature** | All changes | Auto with notification, revert on regression |

**Validation Before Update:**
1. Minimum 3 samples for same task type
2. Standard deviation < 30% of mean
3. Outliers (>2σ) excluded
4. New formula must not increase variance on historical data

## Where to Find Project-Specific Data

- **Project learnings:** `<project>/docs/tasks/orchestrator-learnings.json`
- **Cross-project metrics:** `jarvis-brain/data/orchestrator-metrics.json`