Ln 810 Performance Optimizer

> **Paths:** File paths (`references/`, `../ln-*`) are relative to this skill directory.

**Type:** L2 Domain Coordinator
**Category:** 8XX Optimization

# Performance Optimizer

Runtime-backed multi-cycle optimization coordinator. Profiles, researches, validates, and executes optimization hypotheses until target reached, plateau detected, or budget exhausted.

## Inputs

| Input | Required | Description |
|-------|----------|-------------|
| `target` | Yes | endpoint, function, or pipeline to optimize |
| `observed_metric` | Yes | current performance problem |
| `target_metric` | No | user or research-derived target |
| `max_cycles` | No | default `3` |

## Purpose & Scope

- Detect whether optimization is the right tool
- Run iterative cycles: `profile -> gate -> research -> target -> context -> validate -> execute`
- Preserve optimization artifacts under `.hex-skills/optimization/{slug}/` and runtime state under `.hex-skills/optimization/runtime/runs/{run_id}/`
- Resume deterministically from the last checkpointed phase
- Keep cycle summaries machine-readable

## Runtime Contract

**MANDATORY READ:** Load `references/ci_tool_detection.md`
**MANDATORY READ:** Load `references/coordinator_runtime_contract.md`, `references/optimization_runtime_contract.md`, `references/coordinator_summary_contract.md`

Runtime CLI:

```bash
node references/scripts/optimization-runtime/cli.mjs start --slug {slug} --manifest-file .hex-skills/optimization/{slug}/manifest.json
node references/scripts/optimization-runtime/cli.mjs status --slug {slug}
node references/scripts/optimization-runtime/cli.mjs record-worker-result --payload '{...}'
node references/scripts/optimization-runtime/cli.mjs record-summary --payload '{...}'
node references/scripts/optimization-runtime/cli.mjs record-cycle --payload '{...}'
node references/scripts/optimization-runtime/cli.mjs checkpoint --phase PHASE_8_EXECUTE --payload '{...}'
node references/scripts/optimization-runtime/cli.mjs advance --to PHASE_9_CYCLE_BOUNDARY
```

## Runtime Layout

Runtime state is run-scoped, while optimization artifacts stay slug-scoped:

```text
.hex-skills/optimization/
  runtime/active/ln-810/{slug}.json
  runtime/runs/{run_id}/manifest.json
  runtime/runs/{run_id}/state.json
  runtime/runs/{run_id}/checkpoints.json
  runtime/runs/{run_id}/history.jsonl
  runtime-artifacts/runs/{run_id}/optimization-coordinator/ln-810--{slug}.json
  runtime-artifacts/runs/{run_id}/optimization-worker/{worker}--{child_identifier}.json
  {slug}/context.md
  {slug}/ln-814-log.tsv
```

## Workflow

### Phase 0: Preflight

1. Validate:
   - target identifiable
   - observed metric provided
   - git clean state
   - test infrastructure exists
2. Detect stack and optional service topology.
3. Derive slug.
4. Build manifest with:
   - `slug`
   - `target`
   - `observed_metric`
   - `target_metric`
   - `execution_mode`
   - `cycle_config`
5. Start runtime and checkpoint `PHASE_0_PREFLIGHT`.

### Phase 1: Parse Input

1. Normalize the problem statement.
2. Set or defer `target_metric`.
3. Checkpoint `PHASE_1_PARSE_INPUT`.

### Phase 2: Profile

1. Compute deterministic child metadata:
   - `identifier=ln-811--{slug}--cycle-{current_cycle}`
   - child `run_id`
   - exact `summaryArtifactPath=.hex-skills/runtime-artifacts/runs/{parent_run_id}/optimization-worker/ln-811--{slug}--cycle-{current_cycle}.json`
2. Checkpoint `PHASE_2_PROFILE` with `child_run`.
3. Invoke `ln-811-performance-profiler` with the child `runId` and exact `summaryArtifactPath`.
4. Read the emitted `optimization-worker` summary envelope from the exact artifact path.
5. Record the worker summary with `record-worker-result`.

### Phase 3: Wrong Tool Gate

Evaluate profiler output:

| Gate | Meaning | Action |
|------|---------|--------|
| `PROCEED` | optimization work is justified | continue |
| `CONCERNS` | measurements usable but imperfect | continue with warning |
| `BLOCK` | wrong tool, already optimized, or infrastructure-bound | aggregate and exit |
| `WAIVED` | user overrides `BLOCK` | continue with explicit waiver |

Rules:
- cycle 1 `BLOCK` -> finish as diagnostic result
- cycle 2+ `BLOCK` due to `already_optimized` or `within_industry_norm` -> finish as successful stop

Checkpoint `PHASE_3_WRONG_TOOL_GATE` with:
- `gate_verdict`
- `stop_reason` when blocked
- `final_result` when terminal

### Phase 4: Research

1. Compute deterministic child metadata for `ln-812`.
2. Checkpoint `PHASE_4_RESEARCH` with `child_run`.
3. Invoke `ln-812-optimization-researcher` with the child `runId` and exact `summaryArtifactPath`.
4. Read and record the emitted `optimization-worker` summary envelope.
5. If no hypotheses remain, stop after aggregate/report.

### Phase 5: Set Target

1. Resolve target metric:
   - user-specified target wins
   - otherwise use research target with confidence
   - otherwise default to 50% improvement
2. Checkpoint `PHASE_5_SET_TARGET` with `target_metric`.

### Phase 6: Write Context

1. Build `.hex-skills/optimization/{slug}/context.md`.
2. Include:
   - problem statement
   - performance map
   - target metrics
   - hypotheses and conflicts
   - local codebase findings
   - previous cycles
3. Checkpoint `PHASE_6_WRITE_CONTEXT` with `context_file`.

### Phase 7: Validate Plan

1. Compute deterministic child metadata for `ln-813`.
2. Checkpoint `PHASE_7_VALIDATE_PLAN` with `validation_verdict` and `child_run`.
3. Invoke `ln-813-optimization-plan-validator` with the child `runId` and exact `summaryArtifactPath`.
4. Read and record the emitted `evaluation-coordinator` summary envelope.
5. If verdict is `NO_GO`, pause runtime until user resolves or waives.

### Phase 8: Execute

`execution_mode=execute`:

1. Compute deterministic child metadata for `ln-814`.
2. Checkpoint `PHASE_8_EXECUTE` with `child_run`.
3. Invoke `ln-814-optimization-executor` with the child `runId` and exact `summaryArtifactPath`.
4. Read and record the emitted `optimization-worker` summary envelope.

`execution_mode=plan_only`:

1. Do not run `ln-814`.
2. Checkpoint `PHASE_8_EXECUTE` as `skipped_by_mode`.

### Phase 9: Cycle Boundary

1. Record the cycle summary with `record-cycle`.
2. Evaluate stop conditions:
   - target met
   - plateau
   - max cycles reached
   - no new hypotheses
3. If continuing:
   - merge previous branch when needed
   - increment `current_cycle`
   - checkpoint `PHASE_9_CYCLE_BOUNDARY`
   - advance back to `PHASE_2_PROFILE`
4. If stopping:
   - checkpoint `PHASE_9_CYCLE_BOUNDARY` with `stop_reason`
   - advance to `PHASE_10_AGGREGATE`

### Phase 10: Aggregate

1. Aggregate all cycle summaries from runtime state.
2. Compute cumulative improvement.
3. Checkpoint `PHASE_10_AGGREGATE`.

### Phase 11: Report

1. Produce final report with:
   - per-cycle summary
   - cumulative improvement
   - final result
   - gap analysis when target not met
2. Checkpoint `PHASE_11_REPORT` with:
   - `report_ready=true`
   - `final_result`
3. Record the `optimization-coordinator` summary envelope with `record-summary`.
4. Complete runtime only after the report checkpoint and coordinator summary exist.

## Worker Invocation (MANDATORY)

**Host Skill Invocation:** `Skill(skill: "...", args: "...")` is mandatory delegation.
- Claude: call the Skill tool exactly as shown.
- Codex: if no Skill tool exists, locate the named skill in available skills, read its `SKILL.md`, treat `args` as `$ARGUMENTS`, execute that skill workflow, then return here with its result/artifact.
- Do not inline worker logic or mark the worker complete without executing the target skill.

| Phase | Skill | Purpose |
|-------|--------|---------|
| 2 | `ln-811-performance-profiler` | Build measured performance map |
| 4 | `ln-812-optimization-researcher` | Research hypotheses and targets |
| 7 | `ln-813-optimization-plan-validator` | Validate feasibility via evaluation-platform review (L2 Coordinator) |
| 8 | `ln-814-optimization-executor` | Execute optimization strike and bisect |

```javascript
Skill(skill: "ln-811-performance-profiler")
Skill(skill: "ln-812-optimization-researcher")
Agent(... Skill(skill: "ln-813-optimization-plan-validator"))
Agent(... Skill(skill: "ln-814-optimization-executor"))
```

## TodoWrite format (mandatory)

```
- Start ln-810 runtime (pending)
- Run profiler and record summary (pending)
- Apply Wrong Tool Gate (pending)
- Run researcher and record summary (pending)
- Set target metric (pending)
- Write optimization context (pending)
- Validate plan and record summary (pending)
- Execute or skip by mode (pending)
- Record cycle boundary (pending)
- Aggregate results and write final report (pending)
```

## Critical Rules

- Runtime state is the optimization orchestration SSOT.
- Worker outputs are consumed only through summary JSON artifacts.
- `plan_only` is a first-class execution mode, not an informal branch.
- `NO_GO` from `ln-813` must pause runtime until explicitly resolved.
- Cycle history lives in runtime state, not in chat memory.
- A terminal diagnostic result is still a valid `DONE` orchestration outcome.

## Definition of Done

- [ ] Runtime started and preflight/input checkpoints recorded
- [ ] Profiler and researcher summaries recorded deterministically
- [ ] Wrong Tool Gate result checkpointed
- [ ] Target metric and context file checkpointed
- [ ] Validator summary recorded; `NO_GO` handled via `PAUSED` when needed
- [ ] Executor summary recorded or `skipped_by_mode` checkpointed
- [ ] Cycle boundary recorded for every completed cycle
- [ ] Aggregate and final report checkpoints recorded
- [ ] Runtime completed with final result and resume-free terminal state

## Phase 12: Meta-Analysis

Optional reference: load `references/meta_analysis_protocol.md` only when the user asks for post-run meta-analysis or protocol-formatted run reflection.

Skill type: `optimization-coordinator`. When requested, run after phases complete. Output to chat using the `optimization-coordinator` format.

## Reference Files

- `references/coordinator_runtime_contract.md`
- `references/optimization_runtime_contract.md`
- `references/coordinator_summary_contract.md`
- `../ln-811-performance-profiler/SKILL.md`
- `../ln-812-optimization-researcher/SKILL.md`
- `../ln-813-optimization-plan-validator/SKILL.md`
- `../ln-814-optimization-executor/SKILL.md`

---
**Version:** 3.0.0
**Last Updated:** 2026-03-15