ln-810-performance-optimizer

Paths: File paths (references/, ../ln-*) are relative to this skill directory.

Type: L2 Domain Coordinator Category: 8XX Optimization

Performance Optimizer

Runtime-backed multi-cycle optimization coordinator. Profiles, researches, validates, and executes optimization hypotheses until target reached, plateau detected, or budget exhausted.

Inputs

| Input | Required | Description | |-------|----------|-------------| | target | Yes | endpoint, function, or pipeline to optimize | | observed_metric | Yes | current performance problem | | target_metric | No | user or research-derived target | | max_cycles | No | default 3 |

Purpose & Scope

• Detect whether optimization is the right tool
• Run iterative cycles: profile -> gate -> research -> target -> context -> validate -> execute
• Preserve optimization artifacts under .hex-skills/optimization/{slug}/ and runtime state under .hex-skills/optimization/runtime/runs/{run_id}/
• Resume deterministically from the last checkpointed phase
• Keep cycle summaries machine-readable

Runtime Contract

MANDATORY READ: Load references/ci_tool_detection.md MANDATORY READ: Load references/coordinator_runtime_contract.md, references/optimization_runtime_contract.md, references/coordinator_summary_contract.md

Runtime CLI:

node references/scripts/optimization-runtime/cli.mjs start --slug {slug} --manifest-file .hex-skills/optimization/{slug}/manifest.json
node references/scripts/optimization-runtime/cli.mjs status --slug {slug}
node references/scripts/optimization-runtime/cli.mjs record-worker-result --payload '{...}'
node references/scripts/optimization-runtime/cli.mjs record-summary --payload '{...}'
node references/scripts/optimization-runtime/cli.mjs record-cycle --payload '{...}'
node references/scripts/optimization-runtime/cli.mjs checkpoint --phase PHASE_8_EXECUTE --payload '{...}'
node references/scripts/optimization-runtime/cli.mjs advance --to PHASE_9_CYCLE_BOUNDARY

Runtime Layout

Runtime state is run-scoped, while optimization artifacts stay slug-scoped:

.hex-skills/optimization/
  runtime/active/ln-810/{slug}.json
  runtime/runs/{run_id}/manifest.json
  runtime/runs/{run_id}/state.json
  runtime/runs/{run_id}/checkpoints.json
  runtime/runs/{run_id}/history.jsonl
  runtime-artifacts/runs/{run_id}/optimization-coordinator/ln-810--{slug}.json
  runtime-artifacts/runs/{run_id}/optimization-worker/{worker}--{child_identifier}.json
  {slug}/context.md
  {slug}/ln-814-log.tsv

Workflow

Phase 0: Preflight

1. Validate:
2. target identifiable
3. observed metric provided
4. git clean state
5. test infrastructure exists
6. Detect stack and optional service topology.
7. Derive slug.
8. Build manifest with:
9. slug
10. target
11. observed_metric
12. target_metric
13. execution_mode
14. cycle_config
15. Start runtime and checkpoint PHASE_0_PREFLIGHT.

Phase 1: Parse Input

1. Normalize the problem statement.
2. Set or defer target_metric.
3. Checkpoint PHASE_1_PARSE_INPUT.

Phase 2: Profile

1. Compute deterministic child metadata:
2. identifier=ln-811--{slug}--cycle-{current_cycle}
3. child run_id
4. exact summaryArtifactPath=.hex-skills/runtime-artifacts/runs/{parent_run_id}/optimization-worker/ln-811--{slug}--cycle-{current_cycle}.json
5. Checkpoint PHASE_2_PROFILE with child_run.
6. Invoke ln-811-performance-profiler with the child runId and exact summaryArtifactPath.
7. Read the emitted optimization-worker summary envelope from the exact artifact path.
8. Record the worker summary with record-worker-result.

Phase 3: Wrong Tool Gate

Evaluate profiler output:

| Gate | Meaning | Action | |------|---------|--------| | PROCEED | optimization work is justified | continue | | CONCERNS | measurements usable but imperfect | continue with warning | | BLOCK | wrong tool, already optimized, or infrastructure-bound | aggregate and exit | | WAIVED | user overrides BLOCK | continue with explicit waiver |

Rules:

• cycle 1 BLOCK -> finish as diagnostic result
• cycle 2+ BLOCK due to already_optimized or within_industry_norm -> finish as successful stop

Checkpoint PHASE_3_WRONG_TOOL_GATE with:

• gate_verdict
• stop_reason when blocked
• final_result when terminal

Phase 4: Research

1. Compute deterministic child metadata for ln-812.
2. Checkpoint PHASE_4_RESEARCH with child_run.
3. Invoke ln-812-optimization-researcher with the child runId and exact summaryArtifactPath.
4. Read and record the emitted optimization-worker summary envelope.
5. If no hypotheses remain, stop after aggregate/report.

Phase 5: Set Target

1. Resolve target metric:
2. user-specified target wins
3. otherwise use research target with confidence
4. otherwise default to 50% improvement
5. Checkpoint PHASE_5_SET_TARGET with target_metric.

Phase 6: Write Context

1. Build .hex-skills/optimization/{slug}/context.md.
2. Include:
3. problem statement
4. performance map
5. target metrics
6. hypotheses and conflicts
7. local codebase findings
8. previous cycles
9. Checkpoint PHASE_6_WRITE_CONTEXT with context_file.

Phase 7: Validate Plan

1. Compute deterministic child metadata for ln-813.
2. Checkpoint PHASE_7_VALIDATE_PLAN with validation_verdict and child_run.
3. Invoke ln-813-optimization-plan-validator with the child runId and exact summaryArtifactPath.
4. Read and record the emitted evaluation-coordinator summary envelope.
5. If verdict is NO_GO, pause runtime until user resolves or waives.

Phase 8: Execute

execution_mode=execute:

1. Compute deterministic child metadata for ln-814.
2. Checkpoint PHASE_8_EXECUTE with child_run.
3. Invoke ln-814-optimization-executor with the child runId and exact summaryArtifactPath.
4. Read and record the emitted optimization-worker summary envelope.

execution_mode=plan_only:

1. Do not run ln-814.
2. Checkpoint PHASE_8_EXECUTE as skipped_by_mode.

Phase 9: Cycle Boundary

1. Record the cycle summary with record-cycle.
2. Evaluate stop conditions:
3. target met
4. plateau
5. max cycles reached
6. no new hypotheses
7. If continuing:
8. merge previous branch when needed
9. increment current_cycle
10. checkpoint PHASE_9_CYCLE_BOUNDARY
11. advance back to PHASE_2_PROFILE
12. If stopping:
13. checkpoint PHASE_9_CYCLE_BOUNDARY with stop_reason
14. advance to PHASE_10_AGGREGATE

Phase 10: Aggregate

1. Aggregate all cycle summaries from runtime state.
2. Compute cumulative improvement.
3. Checkpoint PHASE_10_AGGREGATE.

Phase 11: Report

1. Produce final report with:
2. per-cycle summary
3. cumulative improvement
4. final result
5. gap analysis when target not met
6. Checkpoint PHASE_11_REPORT with:
7. report_ready=true
8. final_result
9. Record the optimization-coordinator summary envelope with record-summary.
10. Complete runtime only after the report checkpoint and coordinator summary exist.

Worker Invocation (MANDATORY)

Host Skill Invocation: Skill(skill: "...", args: "...") is mandatory delegation.

• Claude: call the Skill tool exactly as shown.
• Codex: if no Skill tool exists, locate the named skill in available skills, read its SKILL.md, treat args as $ARGUMENTS, execute that skill workflow, then return here with its result/artifact.
• Do not inline worker logic or mark the worker complete without executing the target skill.

| Phase | Skill | Purpose | |-------|--------|---------| | 2 | ln-811-performance-profiler | Build measured performance map | | 4 | ln-812-optimization-researcher | Research hypotheses and targets | | 7 | ln-813-optimization-plan-validator | Validate feasibility via evaluation-platform review (L2 Coordinator) | | 8 | ln-814-optimization-executor | Execute optimization strike and bisect |

Skill(s