ln-814-optimization-executor

What this skill does

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

# ln-814-optimization-executor

**Type:** L3 Worker
**Category:** 8XX Optimization

Executes optimization hypotheses from the researcher using keep/discard autoresearch loop. Supports multi-file changes, compound baselines, and any optimization type (algorithm, architecture, query, caching, batching).

---

## Overview

| Aspect | Details |
|--------|---------|
| **Input** | `.hex-skills/optimization/{slug}/context.md` OR conversation context (standalone invocation) |
| **Output** | Optimized code on isolated branch, per-hypothesis results, experiment log |
| **Pattern** | Strike-first: apply all → test → measure. Bisect only on failure. A/B only for contested alternatives |

---

## Workflow

**Phases:** Pre-flight → Baseline → Strike-First Execution → Report → Gap Analysis

---

## Phase 0: Pre-flight Checks

### Slug Resolution

- If invoked via Agent with contextStore containing `slug` — use directly.
- If invoked standalone — derive slug from context_file path or ask user.

### Step 1: Load Context

Read `.hex-skills/optimization/{slug}/context.md` from project root. Contains problem statement, profiling results, research hypotheses, and target metric.

If file not found: check conversation context for the same data (standalone invocation).

### Step 2: Pre-flight Validation

| Check | Required | Action if Missing |
|-------|----------|-------------------|
| Hypotheses provided (H1..H7) | Yes | Block — nothing to execute |
| Test infrastructure | Yes | Block (see ci_tool_detection.md) |
| Git clean state | Yes | Block (need clean baseline for revert) |
| Worktree isolation | Yes | Create per git_worktree_fallback.md |
| E2E safety test | No (recommended) | Read from context; WARN if null — full test suite as fallback gate |

**MANDATORY READ:** Load `references/git_worktree_fallback.md` — use optimization rows.
**MANDATORY READ:** Load `references/ci_tool_detection.md` — use Test Frameworks + Benchmarks sections.

Tool policy: follow host AGENTS.md MCP preferences; load `references/mcp_tool_preferences.md` and `references/mcp_integration_patterns.md` only when host policy is absent or MCP behavior is unclear..

Use `hex-line` as the primary path for code/config/script edits in this worker. Profilers and benchmarks stay the source of truth; do not treat `hex-graph` as runtime evidence here.

### E2E Safety Test

Read `e2e_test_command` from context file (discovered by profiler during test discovery phase).

| Source | Action |
|--------|--------|
| Context has `e2e_test_command` | Use as functional safety gate in Phase 2 |
| Context has `e2e_test_command = null` | WARN: full test suite is the fallback gate |
| Standalone (no context) | User must provide test command; block if missing |

---

## Phase 1: Establish Baseline

Reuse baseline from performance map (already measured with real metrics).

### From Context File

Read `performance_map.baseline` and `performance_map.test_command` from `.hex-skills/optimization/{slug}/context.md`.

| Field | Source |
|-------|--------|
| `test_command` | Discovered/created test command |
| `baseline` | Multi-metric snapshot: wall time, CPU, memory, I/O |

### Verification Run

Run `test_command` once to confirm baseline is still valid (code unchanged since profiling):

| Step | Action |
|------|--------|
| 1 | Run `test_command` |
| 2 | IF result within 10% of `baseline.wall_time_ms` → baseline confirmed |
| 3 | IF result diverges > 10% → re-measure (3 runs, median) as new baseline |
| 4 | IF test FAILS → BLOCK: "test fails on unmodified code" |

---

## Phase 2: Strike-First Execution

**MANDATORY READ:** Load [optimization_categories.md](references/optimization_categories.md) for pattern reference during implementation.

Apply maximum changes at once. Only fall back to A/B testing where sources genuinely disagree on approach.

### Step 1: Triage Hypotheses

Split hypotheses from researcher into two groups:

| Group | Criteria | Action |
|-------|----------|--------|
| **Uncontested** | Clear best approach, no conflicting alternatives | Apply directly in the strike |
| **Contested** | Multiple approaches exist (e.g., source A says cache, source B says batch) OR `conflicts_with` another hypothesis | A/B test each alternative on top of full implementation |

Most hypotheses should be uncontested — the researcher already ranked them by evidence.

### Step 2: Strike (Apply All Uncontested)

```
1. APPLY all uncontested hypotheses at once (all file edits)
2. VERIFY: Run full test suite
   IF tests FAIL:
     - IF fixable (typo, missing import) → fix & re-run ONCE
     - IF fundamental → BISECT (see Step 4)
3. E2E GATE (if e2e_test_command not null):
   IF FAIL → BISECT
4. MEASURE: 5 runs, median
5. COMPARE: improvement vs baseline
   IF improvement meets target → DONE. Commit all:
     git add {all_files}
     git commit -m "perf: apply optimizations H1,H2,H3,... (+{improvement}%)"
   IF no improvement → BISECT
```

### Step 3: Contested Alternatives (A/B on top of strike)

For each contested pair/group, with ALL uncontested changes already applied:

```
FOR each contested hypothesis group:
  1. Apply alternative A → test → measure (5 runs, median)
  2. Revert alternative A, apply alternative B → test → measure
  3. KEEP the winner. Commit.
  4. Winner becomes part of the baseline for next contested group.
```

### Step 4: Bisect (only on strike failure)

If strike fails tests or shows no improvement:

```
1. Revert all changes: git checkout -- . && git clean -fd
2. Binary search: apply first half of hypotheses → test
   - IF passes → problem in second half
   - IF fails → problem in first half
3. Narrow down to the breaking hypothesis
4. Remove it from strike, re-apply remaining → test → measure
5. Log removed hypothesis with reason
```

### Scope Rules

| Rule | Description |
|------|-------------|
| File scope | Multiple files allowed (not limited to single function) |
| Signature changes | Allowed if tests still pass |
| New files | Allowed (cache wrapper, batch adapter, utility) |
| New dependencies | Allowed if already in project ecosystem (e.g., using configured Redis) |
| Time budget | 45 minutes total |

### Revert Protocol

| Scope | Command |
|-------|---------|
| Full revert | `git checkout -- . && git clean -fd` (safe in worktree) |
| Single hypothesis | `git checkout -- {files}` (only during bisect) |

### Safety Rules

| Rule | Description |
|------|-------------|
| Traceability | Commit message lists all applied hypothesis IDs |
| Isolation | All work in isolated worktree; never modify main worktree |
| Bisect only on failure | Do NOT test hypotheses individually unless strike fails or alternatives genuinely conflict |
| Crash triage | Runtime crash → fix once if trivial (typo, import), else bisect to find cause |

### Stop Conditions (Execution Loop)

| Condition | Action |
|-----------|--------|
| Strike passes + improvement meets target | STOP — commit, proceed to Report |
| All contested alternatives tested | STOP — commit winner, proceed to Report |
| Bisect removes all hypotheses | STOP — report "all hypotheses failed" with profiling data |
| Time budget exceeded (45 min) | STOP — report partial results with remaining hypotheses |
| All tests fail after strike + bisect | STOP — full revert, report diagnostic value only |

---

## Phase 3: Report Results

### Report Schema

| Field | Description |
|-------|-------------|
| baseline | Original measurement (metric + value) |
| final | Final measurement after optimizations |
| total_improvement_pct | Overall percentage improvement |
| target_met | Boolean — did we reach the target metric? |
| strike_result | `clean` (all applied) / `bisected` (some removed) / `failed` |
| hypotheses_applied | List of hypothesis IDs applied in strike |
| hypotheses_removed | List removed during bisect (with reasons) |
| contested_results | Per-contested group: alternative