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

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

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).

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.

Verification Run

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

Phase 2: Strike-First Execution

MANDATORY READ: Load 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:

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

Revert Protocol

Safety Rules

Stop Conditions (Execution Loop)

Phase 3: Report Results

Report Schema

Results Comparison (mandatory)

Show baseline vs final for EVERY metric from performance_map.baseline. Include both percentage and multiplier.

| Metric | Baseline | After Strike | Improvement |
|--------|----------|-------------|-------------|
| Wall time | 7280ms | 3800ms | 47.8% (1.9x) |
| CPU time | 850ms | 720ms | 15.3% (1.2x) |
| Memory peak | 256MB | 245MB | 4.3% |
| HTTP round-trips | 13 | 2 | 84.6% (6.5x) |

Target: 5000ms → Achieved: 3800ms ✓ TARGET MET

Per-Function Delta (if instrumentation available)

If instrumented_files from context is non-empty, run test_command once more AFTER strike to capture per-function timing with the same instrumentation the profiler placed:

| Function | Before (ms) | After (ms) | Delta |
|----------|------------|------------|-------|
| mt_translate | 3500 | 450 | -87% (7.8x) |
| tikal_extract | 2800 | 2800 | 0% (unchanged) |

Then clean up: git checkout -- {instrumented_files} — remove all profiling instrumentation before final commit.

Present both tables to user. This is the primary deliverable — numbers the user sees first.

Experiment Log

Write to {project_root}/.hex-skills/optimization/{slug}/ln-814-log.tsv:

Append to existing file if present (enables tracking across multiple runs).

Phase 4: Gap Analysis (If Target Not Met)

If target metric not reached after all hypotheses:

Error Handling

References

• optimization_categories.md — optimization pattern checklist
• references/ci_tool_detection.md (test + benchmark detection)
• references/git_worktree_fallback.md (worktree isolation)

Runtime Summary Artifact

MANDATORY READ: Load references/coordinator_summary_contract.md

Emit an optimization-worker summary envelope.

Managed mode:

• ln-810 passes deterministic runId and exact summaryArtifactPath
• write the summary to the provided summaryArtifactPath

Standalone mode:

• omit runId and summaryArtifactPath
• write .hex-skills/runtime-artifacts/runs/{run_id}/optimization-worker/ln-814--{identifier}.json

Monitor Integration (Claude Code 2.1.98+)

MANDATORY READ: Load references/monitor_integration_pattern.md

During multi-run optimization cycles (baseline + A/B): Monitor(command="{test_command} 2>&1 | grep --line-buffered -E 'run|result|error|FAIL'", timeout_ms=600000, description="optimization run")

Fallback: if Monitor is unavailable, use Bash(run_in_background=true).

Definition of Done

• Baseline established using same metric type as observed problem
• Hypotheses triaged: uncontested vs contested
• Strike applied: all uncontested hypotheses implemented at once
• Tests pass after strike
• Contested alternatives A/B tested on top of full implementation
• Bisect performed only if strike fails (not preemptively)
• E2E safety test passes (or documented as unavailable)
• Experiment log written to .hex-skills/optimization/{slug}/ln-814-log.tsv
• Report returned with baseline, final, improvement%, strike result
• All changes on isolated branch, pushed to remote
• Gap analysis provided if target metric not met
• Optimization execution artifact written to the shared location

Version: 2.0.0 Last Updated: 2026-03-14