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.

ln-811-algorithm-optimizer

Type: L3 Worker Category: 8XX Optimization Parent: ln-810-performance-optimization-coordinator

Optimizes target function performance via autoresearch loop: establish baseline benchmark, research best practices, generate 3-7 hypotheses, apply each with keep/discard verification.

Overview

| Aspect | Details | |--------|---------| | Input | target_file + target_function (or audit findings from ln-650) | | Output | Optimized function with benchmark proof, optimization report | | Pattern | Autoresearch: modify → benchmark → keep (≥10%) / discard |

Workflow

Phases: Pre-flight → Baseline → Research → Hypothesize → Optimize Loop → Report

Phase 0: Pre-flight Checks

| Check | Required | Action if Missing | |-------|----------|-------------------| | Target file exists | Yes | Block optimization | | Target function identifiable | Yes | Block optimization | | Test infrastructure | Yes | Block optimization (see ci_tool_detection.md) | | Test coverage for target function | Yes | Block — no coverage = no safety net | | Git clean state | Yes | Block (need clean baseline for revert) | | Benchmark infrastructure | No | Generate benchmark (see references) |

MANDATORY READ: Load shared/references/ci_tool_detection.md — use Benchmarks + Test Frameworks sections.

Coverage Verification

Before starting optimization, verify target function has test coverage:

| Step | Action | |------|--------| | 1 | Grep test files for target function name / imports from target module | | 2 | If ≥1 test references target → PROCEED | | 3 | If 0 tests reference target → BLOCK with "no test coverage for {function}" |

Without test coverage, benchmark improvements are meaningless — the optimized function may produce wrong results faster.

Worktree & Branch Isolation

MANDATORY READ: Load shared/references/git_worktree_fallback.md — use ln-811 row.

All work (edits, benchmarks, KEEP commits) in worktree. Never modify main worktree.

Phase 1: Establish Baseline

Step 1.1: Detect or Generate Benchmark

| Situation | Action | |-----------|--------| | Existing benchmark found | Use as-is | | No benchmark exists | Generate minimal benchmark (see benchmark_generation.md) |

Step 1.2: Run Baseline

| Parameter | Value | |-----------|-------| | Runs | 5 | | Metric | Median execution time | | Warm-up | 1 discarded run | | Output | baseline_median, baseline_p95 |

Save baseline result — all improvements measured against this.

Phase 2: Research Best Practices

MANDATORY READ: Load shared/references/research_tool_fallback.md for MCP tool chain.

Research Strategy

| Priority | Tool | Query Template | |----------|------|----------------| | 1 | mcp__context7__query-docs | "{language} {algorithm_type} optimization techniques" | | 2 | mcp__Ref__ref_search_documentation | "{language} {function_name} performance best practices" | | 3 | WebSearch | "{algorithm_type} optimization {language} benchmark {current_year}" |

Research Output

Collect optimization techniques applicable to the target function. For each technique note:

Name and description
Expected improvement category (algorithmic complexity, memory, cache, parallelism)
Applicability conditions (data size, structure, language features)

Phase 3: Generate Hypotheses (3-7)

Hypothesis Sources

MANDATORY READ: Load optimization_categories.md for category checklist.

| Source | Priority | |--------|----------| | Research findings (Phase 2) | 1 | | Optimization categories checklist | 2 | | Code analysis (anti-patterns in target) | 3 |

Hypothesis Format

| Field | Description | |-------|-------------| | id | H1, H2, ... H7 | | category | From optimization_categories.md | | description | What to change | | expected_impact | Estimated improvement % | | risk | Low / Medium / High | | dependencies | Other hypotheses this depends on |

Ordering

Sort by: expected_impact DESC, risk ASC. Independent hypotheses first (no dependencies).

Phase 4: Optimize Loop (Keep/Discard)

Per-Hypothesis Cycle

FOR each hypothesis (H1..H7):
  1. APPLY: Edit target function (surgical change, function body only)
  2. VERIFY: Run tests
     IF tests FAIL (assertion) → DISCARD (revert) → next hypothesis
     IF tests CRASH (runtime error, OOM, import error):
       IF fixable (typo, missing import) → fix & re-run ONCE
       IF fundamental (design flaw, incompatible API) → DISCARD + log "crash: {reason}"
  3. BENCHMARK: Run 5 times, take median
  4. COMPARE: improvement = (baseline - new) / baseline * 100
     IF improvement >= 10% → KEEP:
       git add {target_file}
       git commit -m "perf(H{N}): {description} (+{improvement}%)"
       new baseline = new median
     IF improvement < 10%  → DISCARD (revert edit)
  5. LOG: Record result to experiment log + report

Safety Rules

| Rule | Description | |------|-------------| | Scope | Only target function body; no signature changes | | Dependencies | No new package installations | | Revert | git checkout -- {target_file} on discard | | Time budget | 30 minutes total for all hypotheses | | Compound | Each KEEP becomes new baseline for next hypothesis | | Traceability | Each KEEP = separate git commit with hypothesis ID in message | | Isolation | All work in isolated worktree; never modify main worktree |

Keep/Discard Decision

| Condition | Decision | Action | |-----------|----------|--------| | Tests fail | DISCARD | Revert, log reason | | Improvement ≥ 10% | KEEP | Update baseline | | Improvement 10-20% BUT complexity increase | REVIEW | Log as "marginal + complex", prefer DISCARD | | Improvement < 10% | DISCARD | Revert, log as "insufficient gain" | | Regression (slower) | DISCARD | Revert, log regression amount |

Simplicity criterion (per autoresearch): If improvement is marginal (10-20%) and change significantly increases code complexity (>50% more lines, deeply nested logic, hard-to-read constructs), prefer DISCARD. Simpler code at near-equal performance wins.

Phase 5: Report Results

Report Schema

| Field | Description | |-------|-------------| | target | File path + function name | | baseline | Original median benchmark | | final | Final median after all kept optimizations | | total_improvement | Percentage improvement | | hypotheses_tested | Total count | | hypotheses_kept | Count of kept optimizations | | hypotheses_discarded | Count + reasons | | optimizations[] | Per-kept: id, category, description, improvement% |

Experiment Log

Write to {project_root}/.optimization/ln-811-log.tsv:

| Column | Description | |--------|-------------| | timestamp | ISO 8601 | | hypothesis_id | H1..H7 | | category | From optimization_categories.md | | description | What changed | | baseline_ms | Baseline median before this hypothesis | | result_ms | New median after change | | improvement_pct | Percentage change | | status | keep / discard / crash | | commit | Git commit hash (if kept) |

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

Cleanup

| Action | When | |--------|------| | Remove generated benchmark | If benchmark was auto-generated AND no kept optimizations | | Keep generated benchmark | If any optimization was kept (proof of improvement) |

Configuration

Options:
  # Target
  target_file: ""
  target_function: ""

  # Benchmark
  benchmark_runs: 5
  improvement_threshold: 10    # percent
  warmup_runs: 1

  # Hypotheses
  max_hypotheses: 7
  min_hypotheses: 3

  # Safety
  time_budget_minutes: 30
  allow_new_deps: false
  scope: "function_body"       # function_body | module

  # Verification
  run_tests: true
  run_lint: false

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | No benchmark framework | Stack not in ci_tool_detection.md | Generate inline benchmark | | All hypotheses discarded | No effective optimization found | Report "no improvements found" | | Benchmark noise too high | Inconsistent timing | Increase runs to 10, use p50 | | Test flake | Non-deterministic test | Re-run once; if flakes again, skip hypothesis |

References

benchmark_generation.md
optimization_categories.md
shared/references/ci_tool_detection.md (Benchmarks section)
shared/references/research_tool_fallback.md

Definition of Done

Test coverage for target function verified before optimization
Target function identified and baseline benchmark established (5 runs, median)
Research completed via MCP tool chain (Context7/Ref/WebSearch)
3-7 hypotheses generated, ordered by expected impact
Each hypothesis tested: apply → tests → benchmark → keep/discard
Each kept optimization = separate git commit with hypothesis ID
Kept optimizations compound (each becomes new baseline)
Marginal gains (10-20%) with complexity increase reviewed via simplicity criterion
Tests pass after all kept optimizations
Experiment log written to .optimization/ln-811-log.tsv
Report returned with baseline, final, improvement%, per-hypothesis results
Generated benchmark cleaned up if no optimizations kept
All changes on isolated branch, pushed to remote

Version: 1.0.0 Last Updated: 2026-03-08