ln-810-performance-optimizer
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-810-performance-optimizer
Type: L2 Domain Coordinator Category: 8XX Optimization
Iterative diagnostic pipeline for performance optimization. Profiles the full request stack, classifies bottlenecks, researches industry solutions, and tests optimization hypotheses in multiple cycles — each cycle discovers and addresses different bottlenecks as fixing the dominant one reveals the next (Amdahl's law).
Overview
| Aspect | Details |
|---|---|
| Input | target (endpoint/function/pipeline) + observed_metric (e.g., "6300ms response time") + optional target_metric + optional max_cycles (default 3) |
| Output | Optimized code with verification proof, or diagnostic report with recommendations |
| Workers | ln-811 (profiler) → ln-812 (researcher) → ln-813 (plan validator) → ln-814 (executor) |
| Flow | Phases 0-1 once, then Phases 2-8 loop up to max_cycles times, Phases 9-11 once |
Workflow
Phases: Pre-flight → Parse Input → CYCLE [ Profile → Wrong Tool Gate → Research → Set Target → Write Context → Validate Plan → Execute → Cycle Boundary ] → Collect → Report → Meta-Analysis
Phase 0: Pre-flight Checks
| Check | Required | Action if Missing |
|---|---|---|
| Target identifiable | Yes | Block: "specify file, endpoint, or pipeline to optimize" |
| Observed metric provided | Yes | Block: "specify what metric is slow (e.g., response time, throughput)" |
| Git clean state | Yes | Block: "commit or stash changes first" |
| Test infrastructure | Yes | Block: "tests required for safe optimization" |
| Stack detection | Yes | Detect via ci_tool_detection.md |
| Service topology | No | Detect multi-service architecture (see below) |
| State file | No | If .optimization/{slug}/state.json exists → resume from last completed gate |
MANDATORY READ: Load shared/references/ci_tool_detection.md for test/build detection.
Service Topology Detection
Detect if optimization target spans multiple services with accessible code:
| Signal | How to Detect | Result |
|---|---|---|
| Git submodules | git submodule status — non-empty output |
List of service paths |
| Monorepo | ls for services/, packages/, apps/ directories with independent package files |
List of service paths |
| Docker Compose | docker-compose.yml / compose.yml — map service names to build contexts |
List of service paths + ports |
| Workspace config | pnpm-workspace.yaml, Cargo workspace, Go workspace |
List of module paths |
Output: service_topology — map of service names to code paths. Pass to ln-811 for cross-service tracing.
If single-service (no signals): service_topology = null — standard single-codebase profiling.
State Persistence
Save .optimization/{slug}/state.json after each phase completion. Enables resume on interruption.
{
"target": "src/api/endpoint.py::handler",
"slug": "endpoint-handler",
"cycle_config": { "max_cycles": 3, "plateau_threshold": 5 },
"current_cycle": 1,
"cycles": [
{
"cycle": 1,
"status": "done",
"baseline": { "wall_time_ms": 6300 },
"final": { "wall_time_ms": 3800 },
"improvement_pct": 39.7,
"target_met": false,
"bottleneck": "I/O-Network: 13 sequential HTTP calls",
"hypotheses_applied": ["H1", "H2"],
"branch": "optimize/ln-814-align-endpoint-c1-20260315"
}
],
"phases": {
"0_preflight": { "status": "done", "ts": "2026-03-15T10:00:00Z" },
"2_profile": { "status": "done", "ts": "2026-03-15T10:05:00Z", "worker": "ln-811" },
"8_execute": { "status": "pending" }
}
}
Phase status values: pending → running → done | failed
Update state BEFORE and AFTER each phase. For Agent-delegated phases (7, 8): set running before launch, done/failed after Agent returns.
On startup: if .optimization/{slug}/state.json exists, ask user: "Resume from cycle {current_cycle}, phase {last incomplete}?" or "Start fresh?"
Phases are per-cycle — reset at each cycle boundary. current_cycle + phases tells the exact resumption point.
Cycle Management
| Parameter | Default | Description |
|---|---|---|
| max_cycles | 3 | Maximum optimization cycles |
| plateau_threshold | 5 | Minimum improvement % to continue to next cycle |
Each cycle: Profile → Gate → Research → Target → Context → Validate → Execute. Each cycle naturally discovers different bottlenecks (fixing dominant reveals next per Amdahl's law).
Stop Conditions (evaluated after each cycle)
| Condition | Action |
|---|---|
target_met |
STOP — target reached |
improvement < plateau_threshold % |
STOP — plateau detected |
cycle == max_cycles |
STOP — budget exhausted |
| ln-812 returns 0 hypotheses | STOP — no further optimization found |
Between Cycles
1. Collect cycle results (improvement, branch, hypotheses applied)
2. Merge cycle branch: git merge {cycle_branch} --no-edit
3. Record cycle summary in state.json
4. Run /compact to compress conversation context
5. Display: ═══ CYCLE {N}/{max} ═══ Previous: {bottleneck} → {improvement}%
6. Reset phase statuses in state.json for new cycle
If merge has conflicts → BLOCK: report partial results, user resolves manually.
Phase 1: Parse Input
Parse user input into structured problem statement:
| Field | Source | Example |
|---|---|---|
| target | User-specified | src/api/alignment.py::align_endpoint, /api/v1/align, alignment pipeline |
| observed_metric | User-specified | { value: 6300, unit: "ms", type: "response_time" } |
| target_metric | User-specified OR Phase 5 | { value: 500, unit: "ms" } or null |
| max_cycles | User-specified OR default | 3 |
| audit_report | Optional | Path to ln-650 output (additional hints for profiler) |
If target_metric not provided by user, defer to Phase 5 (after research establishes industry benchmark).
Generate slug
Derive {slug} from target for per-task isolation: sanitize to [a-z0-9_-], max 50 chars.
| Target | Slug |
|---|---|
src/api/alignment.py::align_endpoint |
align-endpoint |
test_idml_structure_preserved |
test-idml-structure-preserved |
/api/v1/translate |
api-v1-translate |
All artifacts go to .optimization/{slug}/: context.md, state.json, ln-814-log.tsv, profile_test.sh.
CYCLE LOOP: Phases 2-8
FOR cycle = 1 to max_cycles:
IF cycle > 1:
1. Merge previous cycle branch: git merge {previous_branch} --no-edit
2. /compact — compress conversation context
3. Display cycle header:
═══ CYCLE {cycle}/{max_cycles} ═══
Previous: {bottleneck} → {improvement}% improvement
Remaining gap: {current_metric} vs target {target_metric}
4. Reset phases in state.json
5. Update current_cycle in state.json
Phase 2: Profile
Phase 3: Wrong Tool Gate
Phase 4: Research
Phase 5: Set Target (cycle 1 only — persists across cycles)
Phase 6: Write Context
Phase 7: Validate Plan
Phase 8: Execute
CYCLE BOUNDARY: evaluate stop conditions (see below)
Phase 2: Profile — DELEGATE to ln-811
Do NOT trace code, read function bodies, or profile yourself. INVOKE the profiler skill.
Invoke: Skill(skill: "ln-811-performance-profiler")
Pass: problem statement from Phase 1 + audit_report path (if provided).
On cycle 2+: pass same problem statement. ln-811 re-profiles the now-optimized code — test_command is rediscovered, new baseline measured, new bottlenecks found.
ln-811 will: discover/create test → run baseline (multi-metric) → static analysis + suspicion stack → instrument → build performance map.
Receive: performance_map, suspicion_stack, optimization_hints, wrong_tool_indicators, e2e_test info.
Phase 3: Wrong Tool Gate (4-Level Verdict)
Evaluate profiler results using structured verdict (adapted from ln-500 quality gate model).
| Verdict | Condition | Action |
|---|---|---|
| PROCEED | wrong_tool_indicators empty, measurements stable |
Continue to Phase 4 (research) |
| CONCERNS | Measurement variance > 20% OR baseline unstable OR partial metrics only | Continue with warning — note uncertainty in context file |
| BLOCK | external_service_no_alternative OR infrastructure_bound OR already_optimized OR within_industry_norm |
See below |
| WAIVED | User explicitly overrides BLOCK ("try anyway") | Continue despite indicators — log user override |
BLOCK on Cycle 2+
On cycle 2+, already_optimized or within_industry_norm is a SUCCESS signal — previous cycles brought performance to acceptable level. Break the cycle loop and proceed to Phase 9 (Final Report).
BLOCK Diagnostics
| Indicator | Diagnostic Message |
|---|---|
external_service_no_alternative |
"Bottleneck is {service} latency ({X}ms). Recommend: negotiate SLA / switch provider / add cache layer." |
within_industry_norm |
"Current performance ({X}ms) is within industry norm ({Y}ms). No optimization needed." |
infrastructure_bound |
"Bottleneck is infrastructure ({detail}). Recommend: scaling / caching / CDN." |
already_optimized |
"Code already uses optimal patterns. Consider infrastructure scaling." |
Exit format: Always provide diagnostic report with performance_map — the profiling data is valuable regardless of verdict.
Phase 4: Research — DELEGATE to ln-812
Do NOT research benchmarks or generate hypotheses yourself. INVOKE the researcher skill.
Invoke: Skill(skill: "ln-812-optimization-researcher")
Context available: performance_map from Phase 2 (in shared conversation).
On cycle 2+: provide in conversation context before invoking: "Previously applied hypotheses (exclude from research): {list with descriptions}. Research NEW bottlenecks only." This is natural Skill() conversation, not structural coupling — ln-812 remains standalone-invocable.
ln-812 will: competitive analysis → target metrics → bottleneck-specific research → local codebase check → generate hypotheses H1..H7.
Receive: industry_benchmark, target_metrics, hypotheses (H1..H7 with conflicts_with), local_codebase_findings, research_sources.
If ln-812 returns 0 hypotheses → STOP: no further optimization found. Proceed to Phase 9.
Phase 5: Set Target Metric
Cycle 1 only. Target is set once and persists across all cycles. What changes between cycles is the baseline (each cycle's final becomes next cycle's baseline).
Multi-Metric Target Resolution
FOR each metric in target_metrics from ln-812:
IF user provided target for this metric → use
ELIF ln-812 target_metrics[metric].confidence in [HIGH, MEDIUM] → use
ELSE → baseline × 0.5 (50% default)
Primary metric (for stop condition) = metric type from observed_metric (what user complained about).
Backwards-Compatible Single Target
| Situation | Action |
|---|---|
User provided target_metric |
Use as primary target |
| User did not provide; ln-812 found target_metrics | Use target_metrics.{primary_metric_type} |
| Neither available | Set to 50% improvement as default target |
Phase 6: Write Optimization Context
Serialize diagnostic results from Phases 2-5 into structured context.
- Normal mode: write
.optimization/{slug}/context.mdin project root — input for ln-813/ln-814 - Plan mode: write same structure to plan file (file writes restricted) → call ExitPlanMode
Context file is overwritten each cycle — it is a transient handoff to workers. Cycle history lives in state.json and experiment log (ln-814-log.tsv).
Context file structure:
| Section | Source | Content |
|---|---|---|
| Problem Statement | Phase 1 | target, observed_metric, target_metric |
| Performance Map | ln-811 | Full performance_map (real measurements: baseline, per-step metrics, bottleneck classification) |
| Suspicion Stack | ln-811 | Confirmed + dismissed suspicions with evidence |
| Industry Benchmark | ln-812 | expected_range, source, recommended_target |
| Target Metrics | ln-812 | Structured per-metric targets with confidence |
| Hypotheses | ln-812 | Table: ID, description, bottleneck_addressed, expected_impact, complexity, risk, files_to_modify, conflicts_with |
| Dependencies/Conflicts | ln-812 | H2 requires H1; H3 conflicts with H1 (used by ln-814 for contested vs uncontested triage) |
| Local Codebase Findings | ln-812 | Batch APIs, cache infra, connection pools found in code |
| Test Command | ln-811 | Command used for profiling (reused for post-optimization measurement) |
| E2E Test | ln-811 | E2E safety test command + source (functional gate for executor) |
| Instrumented Files | ln-811 | List of files with active instrumentation (ln-814 cleans up after strike) |
| Previous Cycles | state.json | Per-cycle summary: cycle number, bottleneck, improvement %, hypotheses applied |
Worker Delegation Strategy
| Worker | Tool | Rationale |
|---|---|---|
| ln-811 | Skill() | Needs problem_statement from conversation. First heavy worker — context clean |
| ln-812 | Skill() | Needs performance_map from ln-811 conversation output. Context still manageable (~11K) |
| ln-813 | Agent() | Reads ALL input from context.md on disk. Zero conversation dependency. Isolated context prevents degradation |
| ln-814 | Agent() | Reads ALL input from context.md on disk. Zero conversation dependency. Heaviest worker benefits most from fresh context |
Phase 6 (Write Context) is the natural handoff boundary: shared context → isolated context.
Phase 7: Validate Plan — DELEGATE to ln-813 (Isolated Context)
Do NOT validate the plan yourself. INVOKE the plan validator via Agent for context isolation.
Invoke:
Agent(description: "Validate optimization plan",
prompt: "Execute worker.
Step 1: Invoke worker:
Skill(skill: \"ln-813-optimization-plan-validator\")
CONTEXT:
{\"slug\": \"{slug}\", \"context_file\": \".optimization/{slug}/context.md\"}",
subagent_type: "general-purpose")
Update state.json: set phase 7_validate status to running before launch.
ln-813 will: agent review (Codex + Gemini) + own feasibility check → GO/GO_WITH_CONCERNS/NO_GO.
Receive (from Agent return): verdict (GO/GO_WITH_CONCERNS/NO_GO), corrections_applied count, hypotheses_removed list, concerns.
After Agent returns — re-read .optimization/{slug}/context.md for applied corrections. Update state.json: set phase 7_validate to done or failed.
| Verdict | Action |
|---|---|
| GO | Proceed to Phase 8 |
| GO_WITH_CONCERNS | Proceed with warnings logged |
| NO_GO | Present issues to user. Ask: proceed (WAIVE) or stop |
Phase 8: Execute — DELEGATE to ln-814 (Isolated Context)
In Plan Mode: SKIP this phase. Context file from Phase 6 IS the plan. Call ExitPlanMode.
Do NOT implement optimizations yourself. INVOKE the executor via Agent for context isolation.
Invoke:
Agent(description: "Execute optimization strike",
prompt: "Execute worker.
Step 1: Invoke worker:
Skill(skill: \"ln-814-optimization-executor\")
CONTEXT:
{\"slug\": \"{slug}\", \"context_file\": \".optimization/{slug}/context.md\"}",
subagent_type: "general-purpose")
Update state.json: set phase 8_execute status to running before launch.
ln-814 will: read context → create worktree → strike-first (apply all) → test → measure → bisect if needed → report.
Receive (from Agent return): branch, baseline, final, total_improvement_pct, target_met, strike_result, hypotheses_applied, hypotheses_removed, files_modified.
After Agent returns — read .optimization/{slug}/ln-814-log.tsv for experiment details. Update state.json: set phase 8_execute to done or failed.
Cycle Boundary (after Phase 8)
Step 1: Collect Cycle Results
Verify Agent workers completed successfully:
| Worker | Check | On failure |
|---|---|---|
| ln-813 | Agent returned text containing verdict keyword (GO/NO_GO/GO_WITH_CONCERNS) | Set phase 7_validate to failed, report to user |
| ln-814 | Agent returned text with baseline + final metrics | Set phase 8_execute to failed, report partial results |
Extract from ln-814:
| Field | Description |
|---|---|
| branch | Worktree branch with optimizations |
| baseline | Original measurement |
| final | Measurement after optimizations |
| total_improvement_pct | Overall improvement |
| target_met | Whether target metric was reached |
| strike_result | clean / bisected / failed |
| hypotheses_applied | IDs applied in strike |
| hypotheses_removed | IDs removed during bisect (with reasons) |
| contested_results | Per-group: alternatives tested, winner, measurement |
| files_modified | All changed files |
Step 2: Record Cycle Summary
Save to state.json.cycles[]:
{
"cycle": 1,
"status": "done",
"baseline": { "wall_time_ms": 6300 },
"final": { "wall_time_ms": 3800 },
"improvement_pct": 39.7,
"target_met": false,
"bottleneck": "I/O-Network: 13 sequential HTTP calls",
"hypotheses_applied": ["H1", "H2"],
"branch": "optimize/ln-814-align-endpoint-c1-20260315"
}
Step 3: Evaluate Stop Conditions
| Check | Result | Action |
|---|---|---|
target_met == true |
SUCCESS | Break → Phase 9 with "TARGET MET on cycle {N}" |
improvement_pct < plateau_threshold |
PLATEAU | Break → Phase 9 with "PLATEAU on cycle {N}: {improvement}% < {threshold}%" |
cycle == max_cycles |
BUDGET | Break → Phase 9 with "MAX CYCLES reached ({N}/{max})" |
| None of the above | CONTINUE | Proceed to next cycle (merge → compact → Phases 2-8) |
Phase 9: Aggregate Results
Collect results across ALL completed cycles from state.json.cycles[] and ln-814-log.tsv.
Compute:
- Total improvement:
(original_baseline - final_of_last_cycle) / original_baseline × 100 - Per-cycle gains: array of improvement percentages
- Cumulative hypotheses applied/removed across all cycles
Phase 10: Final Report
Cycle Summary Table
| Cycle | Bottleneck | Baseline | Final | Improvement | Hypotheses | Branch |
|-------|------------|----------|-------|-------------|------------|--------|
| 1 | I/O-Network (13 HTTP) | 6300ms | 3800ms | 39.7% | H1,H2 | opt/...-c1 |
| 2 | CPU (O(n^2) alignment) | 3800ms | 1200ms | 68.4% | H1,H3 | opt/...-c2 |
| 3 | I/O-File (temp files) | 1200ms | 480ms | 60.0% | H1 | opt/...-c3 |
| **Total** | | **6300ms** | **480ms** | **92.4%** | | |
Target: 500ms → Achieved: 480ms ✓ TARGET MET (cycle 3)
Per-Cycle Detail
For each cycle, include:
| Section | Content |
|---|---|
| Problem | Original target + observed metric |
| Diagnosis | Bottleneck type + detail from profiler |
| Target | User-provided or research-derived (same across cycles) |
| Result | Final metric + improvement % + strike result |
| Optimizations Applied | Hypotheses applied: id, description |
| Optimizations Removed | Hypotheses removed during bisect: id, reason |
| Contested Alternatives | Per-group: alternatives tested, winner, measurement delta |
If Target Not Met
Include gap analysis from last cycle's ln-814:
- What was achieved (cumulative improvement %)
- Remaining bottlenecks from latest time map
- Infrastructure/architecture recommendations beyond code changes
- Stop reason: plateau / max_cycles / no hypotheses
Branches
List all cycle branches for user review. Final branch contains all optimizations.
Phase 11: Meta-Analysis
MANDATORY READ: Load shared/references/meta_analysis_protocol.md
Skill type: optimization-coordinator.
Error Handling
Per-Phase Errors
| Phase | Error | Recovery |
|---|---|---|
| 2 (Profile) | Cannot trace target | Report "cannot identify code path for {target}" |
| 3 (Gate) | Wrong tool exit (cycle 1) | Report diagnosis + recommendations, do NOT proceed |
| 3 (Gate) | Wrong tool exit (cycle 2+, ALREADY_OPTIMIZED) | SUCCESS — break to Phase 9 |
| 4 (Research) | No solutions found | Report bottleneck but "no known optimization pattern for {type}" |
| 4 (Research) | 0 hypotheses (cycle 2+) | STOP — no further optimization. Proceed to Phase 9 |
| 7 (Validate) | NO_GO verdict | Present issues to user, offer WAIVE or stop |
| 8 (Execute) | All hypotheses fail | Report profiling + research as diagnostic value |
| 8 (Execute) | Worker timeout | Report partial results |
| Cycle boundary | Merge conflict | BLOCK: report partial results, list completed cycles |
Fatal Errors
| Error | Action |
|---|---|
| Target not resolvable | Block: "cannot find {target} in codebase" |
| No test infrastructure | Block: "tests required for safe optimization" |
| Dirty git state | Block: "commit or stash changes first" |
Plan Mode Support: Phased Gate Pattern
Alternates between plan mode (approval gates) and execution.
GATE 1 — Plan profiling (cycle 1 only)
Plan Mode: Phase 0-1 (preflight, parse input)
→ Present: what will be profiled, which test, which metrics, max_cycles
→ ExitPlanMode (user approves profiling)
EXECUTE 1 — Run profiling (cycle 1)
Phase 2: Skill("ln-811") — runtime profiling (needs Bash)
Phase 3: Wrong Tool Gate (evaluate real measurements)
→ If wrong tool → EXIT with diagnostic
GATE 2 — Plan research & execution (cycle 1 only)
EnterPlanMode: present performance_map to user
Phase 4: Skill("ln-812") — research (read-only, runs in plan mode)
Phase 5: Set target metric (multi-metric)
Phase 6: Write context file
→ Present: hypotheses, target metrics, execution plan, max_cycles
→ ExitPlanMode (user approves strike + cycle loop)
EXECUTE 2+ — Validate + Execute + Loop
Phase 7: Agent("ln-813") — plan review in ISOLATED context (GO/NO_GO)
Phase 8: Agent("ln-814") — strike execution in ISOLATED context
[Cycle boundary → merge → /compact]
Phase 2-8 (cycle 2, auto-continue)
[Cycle boundary → merge → /compact]
Phase 2-8 (cycle 3, auto-continue)
Phase 9-11: Aggregate, report, meta-analysis
Cycles 2+ auto-continue — user already approved optimization goal. Stop conditions protect against waste.
References
../ln-811-performance-profiler/SKILL.md(profiler worker)../ln-812-optimization-researcher/SKILL.md(researcher worker)../ln-813-optimization-plan-validator/SKILL.md(plan validator worker)../ln-814-optimization-executor/SKILL.md(executor worker)shared/references/ci_tool_detection.md(tool detection)shared/references/meta_analysis_protocol.md(meta-analysis)
Definition of Done
- Input parsed into structured problem statement (target, metric, max_cycles)
- Multi-cycle loop executed (up to max_cycles or until stop condition)
- Each cycle: profiled → gated → researched → validated → executed
- Target metrics established from ln-812 research (multi-metric)
- Context compacted between cycles (
/compact) - Previous cycle branches merged before re-profiling
- Cycle summary table in final report (per-cycle + cumulative)
- All cycle branches listed for user review
- Stop condition documented (target_met / plateau / max_cycles / no hypotheses)
- Meta-analysis completed with cycle metrics
Version: 3.0.0 Last Updated: 2026-03-15