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:
   • target identifiable
   • observed metric provided
   • git clean state
   • test infrastructure exists
2. Detect stack and optional service topology.
3. Derive slug.
4. Build manifest with:
   • slug
   • target
   • observed_metric
   • target_metric
   • execution_mode
   • cycle_config
5. 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:
   • identifier=ln-811--{slug}--cycle-{current_cycle}
   • child run_id
   • exact summaryArtifactPath=.hex-skills/runtime-artifacts/runs/{parent_run_id}/optimization-worker/ln-811--{slug}--cycle-{current_cycle}.json
2. Checkpoint PHASE_2_PROFILE with child_run.
3. Invoke ln-811-performance-profiler with the child runId and exact summaryArtifactPath.
4. Read the emitted optimization-worker summary envelope from the exact artifact path.
5. 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:
   • user-specified target wins
   • otherwise use research target with confidence
   • otherwise default to 50% improvement
2. Checkpoint PHASE_5_SET_TARGET with target_metric.

Phase 6: Write Context

1. Build .hex-skills/optimization/{slug}/context.md.
2. Include:
   • problem statement
   • performance map
   • target metrics
   • hypotheses and conflicts
   • local codebase findings
   • previous cycles
3. 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:
   • target met
   • plateau
   • max cycles reached
   • no new hypotheses
3. If continuing:
   • merge previous branch when needed
   • increment current_cycle
   • checkpoint PHASE_9_CYCLE_BOUNDARY
   • advance back to PHASE_2_PROFILE
4. If stopping:
   • checkpoint PHASE_9_CYCLE_BOUNDARY with stop_reason
   • 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:
   • per-cycle summary
   • cumulative improvement
   • final result
   • gap analysis when target not met
2. Checkpoint PHASE_11_REPORT with:
   • report_ready=true
   • final_result
3. Record the optimization-coordinator summary envelope with record-summary.
4. 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(skill: "ln-811-performance-profiler")
Skill(skill: "ln-812-optimization-researcher")
Agent(... Skill(skill: "ln-813-optimization-plan-validator"))
Agent(... Skill(skill: "ln-814-optimization-executor"))

TodoWrite format (mandatory)

- Start ln-810 runtime (pending)
- Run profiler and record summary (pending)
- Apply Wrong Tool Gate (pending)
- Run researcher and record summary (pending)
- Set target metric (pending)
- Write optimization context (pending)
- Validate plan and record summary (pending)
- Execute or skip by mode (pending)
- Record cycle boundary (pending)
- Aggregate results and write final report (pending)

Critical Rules

• Runtime state is the optimization orchestration SSOT.
• Worker outputs are consumed only through summary JSON artifacts.
• plan_only is a first-class execution mode, not an informal branch.
• NO_GO from ln-813 must pause runtime until explicitly resolved.
• Cycle history lives in runtime state, not in chat memory.
• A terminal diagnostic result is still a valid DONE orchestration outcome.

Definition of Done

• Runtime started and preflight/input checkpoints recorded
• Profiler and researcher summaries recorded deterministically
• Wrong Tool Gate result checkpointed
• Target metric and context file checkpointed
• Validator summary recorded; NO_GO handled via PAUSED when needed
• Executor summary recorded or skipped_by_mode checkpointed
• Cycle boundary recorded for every completed cycle
• Aggregate and final report checkpoints recorded
• Runtime completed with final result and resume-free terminal state

Phase 12: Meta-Analysis

Optional reference: load references/meta_analysis_protocol.md only when the user asks for post-run meta-analysis or protocol-formatted run reflection.

Skill type: optimization-coordinator. When requested, run after phases complete. Output to chat using the optimization-coordinator format.

Reference Files

• references/coordinator_runtime_contract.md
• references/optimization_runtime_contract.md
• references/coordinator_summary_contract.md
• ../ln-811-performance-profiler/SKILL.md
• ../ln-812-optimization-researcher/SKILL.md
• ../ln-813-optimization-plan-validator/SKILL.md
• ../ln-814-optimization-executor/SKILL.md

---

Version: 3.0.0 Last Updated: 2026-03-15