127 lines
4.3 KiB
Markdown
127 lines
4.3 KiB
Markdown
# 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`
|