ln-810-performance-optimizer

> **Paths:** File paths (`shared/`, `references/`, `../ln-*`) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root. If `shared/` is missing, fetch files via WebFetch from `https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}`.

**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 `shared/references/ci_tool_detection.md`
**MANDATORY READ:** Load `shared/references/coordinator_runtime_contract.md`, `shared/references/optimization_runtime_contract.md`, `shared/references/coordinator_summary_contract.md`

Runtime CLI:

```bash
node shared/scripts/optimization-runtime/cli.mjs start --slug {slug} --manifest-file .hex-skills/optimization/{slug}/manifest.json
node shared/scripts/optimization-runtime/cli.mjs status --slug {slug}
node shared/scripts/optimization-runtime/cli.mjs record-worker-result --worker ln-811 --payload '{...}'
node shared/scripts/optimization-runtime/cli.mjs record-cycle --payload '{...}'
node shared/scripts/optimization-runtime/cli.mjs checkpoint --phase PHASE_8_EXECUTE --payload '{...}'
node shared/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
  {slug}/context.md
  runtime-artifacts/optimization-profile/{slug}.json
  runtime-artifacts/optimization-research/{slug}.json
  runtime-artifacts/optimization-validation/{slug}.json
  runtime-artifacts/optimization-execution/{slug}.json
  {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. Invoke `ln-811-performance-profiler`.
2. Read `.hex-skills/runtime-artifacts/runs/{run_id}/optimization-profile/{slug}.json`.
3. Record the worker result with `record-worker-result`.
4. Checkpoint `PHASE_2_PROFILE`.

### 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. Invoke `ln-812-optimization-researcher`.
2. Read `.hex-skills/runtime-artifacts/runs/{run_id}/optimization-research/{slug}.json`.
3. Record the worker result.
4. If no hypotheses remain, stop after aggregate/report.
5. Checkpoint `PHASE_4_RESEARCH`.

### 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. Invoke `ln-813-optimization-plan-validator`.
2. Read `.hex-skills/runtime-artifacts/runs/{run_id}/optimization-validation/{slug}.json`.
3. Record worker result.
4. Checkpoint `PHASE_7_VALIDATE_PLAN`.
5. If verdict is `NO_GO`, pause runtime until user resolves or waives.

### Phase 8: Execute

`execution_mode=execute`:

1. Invoke `ln-814-optimization-executor`.
2. Read `.hex-skills/runtime-artifacts/runs/{run_id}/optimization-execution/{slug}.json`.
3. Record worker result.
4. Checkpoint `PHASE_8_EXECUTE` with `execution_result`.

`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. Complete runtime only after this checkpoint exists.

## Worker Invocation (MANDATORY)

| Phase | Worker | 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 runtime-backed review |
| 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

**MANDATORY READ:** Load `shared/references/meta_analysis_protocol.md`

Skill type: `optimization-coordinator`. Run after phases complete. Output to chat using the `optimization-coordinator` format.

## Reference Files

- `shared/references/coordinator_runtime_contract.md`
- `shared/references/optimization_runtime_contract.md`
- `shared/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