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