# Orchestrator Learnings JSON Schema

Reference documentation for `orchestrator-learnings.json` structure.

## Root Object

```json
{
  "schema_version": "1.0",
  "project": "string - Project identifier",
  "milestone": "string - Milestone identifier",
  "created_at": "ISO8601 - When file was created",
  "learnings": [],
  "phase_summaries": [],
  "proposed_adjustments": [],
  "investigation_queue": []
}
```

## Learning Entry

Captured when |variance| > 50%.

```json
{
  "task_id": "string - Matches task ID from tasks.md (e.g., MS-SEC-001)",
  "task_type": "enum - See Task Types below",
  "estimate_k": "number - Estimated tokens in thousands",
  "actual_k": "number - Actual tokens used in thousands",
  "variance_pct": "number - ((actual - estimate) / estimate) * 100",
  "characteristics": {
    "file_count": "number - Files modified",
    "keywords": ["array - Descriptive tags for pattern matching"]
  },
  "analysis": "string - Human/AI explanation of variance",
  "flags": ["array - CRITICAL | NEEDS_INVESTIGATION | ANOMALY"],
  "captured_at": "ISO8601 - When learning was recorded"
}
```

### Task Types

| Type                     | Description                                | Base Estimate    |
| ------------------------ | ------------------------------------------ | ---------------- |
| `STYLE_FIX`              | Formatting, prettier, lint fixes           | 3-5K             |
| `BULK_CLEANUP`           | Multi-file cleanup (unused vars, warnings) | file_count × 550 |
| `GUARD_ADD`              | Add guards, decorators, validation         | 5-8K             |
| `AUTH_ADD`               | Authentication implementation              | 15-25K           |
| `ERROR_HANDLING`         | Error handling improvements                | 8-12K            |
| `CONFIG_DEFAULT_CHANGE`  | Config default changes                     | 5-10K            |
| `CONFIG_EXTERNALIZATION` | Move hardcoded values to env vars          | 8-12K            |
| `INPUT_VALIDATION`       | Input sanitization, allowlists             | 5-8K             |
| `BUG_FIX_SIMPLE`         | Simple bug fixes (single file)             | 3-8K             |
| `REFACTOR`               | Code refactoring                           | 10-15K           |
| `COMPLEX_REFACTOR`       | Multi-file architectural changes           | 25-40K           |
| `TEST_ADD`               | Adding test coverage                       | 15-25K           |

## Phase Summary

Generated after phase verification task.

```json
{
  "phase": "number - Phase number",
  "tasks_completed": "number",
  "tasks_total": "number",
  "estimate_total_k": "number - Sum of estimates",
  "actual_total_k": "number - Sum of actual usage",
  "variance_avg_pct": "number - Average variance",
  "pattern": "enum - SYSTEMATIC_UNDERESTIMATE | ACCURATE | OVERESTIMATE",
  "notes": "string - Summary observations"
}
```

## Proposed Adjustment

Heuristic improvement proposals.

```json
{
  "category": "string - Task type category",
  "current_heuristic": "string - Current estimation formula",
  "proposed_heuristic": "string - Improved formula",
  "confidence": "enum - HIGH | MEDIUM | LOW",
  "evidence": ["array - Task IDs supporting this"],
  "variance_if_applied": "string - Expected improvement",
  "notes": "string - Additional context"
}
```

## Investigation Queue

Tasks requiring manual review.

```json
{
  "task_id": "string",
  "question": "string - What needs investigation",
  "priority": "enum - HIGH | MEDIUM | LOW",
  "status": "enum - OPEN | IN_PROGRESS | CLOSED",
  "resolution": "string - Outcome when closed",
  "verified_at": "ISO8601 - When investigation completed"
}
```

## Variance Thresholds

| Variance | Action                                |
| -------- | ------------------------------------- |
| 0-30%    | Log only (acceptable)                 |
| 30-50%   | Flag for review                       |
| 50-100%  | Capture learning                      |
| >100%    | CRITICAL — review task classification |