ln-814-optimization-executor

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: alternatives