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

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

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:

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

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)

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:

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.

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

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

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

Phase 6: Write Optimization Context

Serialize diagnostic results from Phases 2-5 into structured context.

• Normal mode: write .optimization/{slug}/context.md in 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:

Worker Delegation Strategy

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.

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:

Extract from ln-814:

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

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:

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

Fatal Errors

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