levalencia 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