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. If
shared/
is missing, fetch files via WebFetch from
https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/{path}
.

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.

json

{
  "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)

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

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

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

done

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

done

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[]

json

{
  "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

ln-810-performance-optimizer

NPX Install

Tags

SKILL.md Content

ln-810-performance-optimizer

Overview

Workflow

Phase 0: Pre-flight Checks

Service Topology Detection

State Persistence

Cycle Management

Stop Conditions (evaluated after each cycle)

Between Cycles

Phase 1: Parse Input

Generate slug

CYCLE LOOP: Phases 2-8

Phase 2: Profile — DELEGATE to ln-811

Phase 3: Wrong Tool Gate (4-Level Verdict)

BLOCK on Cycle 2+

BLOCK Diagnostics

Phase 4: Research — DELEGATE to ln-812

Phase 5: Set Target Metric

Multi-Metric Target Resolution

Backwards-Compatible Single Target

Phase 6: Write Optimization Context

Worker Delegation Strategy

Phase 7: Validate Plan — DELEGATE to ln-813 (Isolated Context)

Phase 8: Execute — DELEGATE to ln-814 (Isolated Context)

Cycle Boundary (after Phase 8)

Step 1: Collect Cycle Results

Step 2: Record Cycle Summary

Step 3: Evaluate Stop Conditions

Phase 9: Aggregate Results

Phase 10: Final Report

Cycle Summary Table

Per-Cycle Detail

If Target Not Met

Branches

Phase 11: Meta-Analysis

Error Handling

Per-Phase Errors

Fatal Errors

Plan Mode Support: Phased Gate Pattern

References

Definition of Done