Ln 44 Performance Optimizer

Performance Optimizer

Goal: Optimize only measured problems. Preserve correctness, isolate experiments, and retain a change only when comparable evidence shows that it improves the agreed metric without unacceptable regressions.

Execution contract: The checklist defines completion. Track each item internally as PENDING, PROVEN with evidence, CLEARED with evidence its condition is absent, or UNPROVEN with a gap; reading, delegation, tool failure, a zero exit status, or a self-reported success is not proof; only the observed outcome is. Reconcile after each section. Before returning, resolve all PENDING, count only PROVEN and CLEARED, and apply verdict and approval rules to every gap. Preserve intent, scope, and existing authorization. Continue authorized work; ask only for consequential unresolved choices or required external approval. When no one can answer during the run, state the exact question and apply the skill's verdict for the remaining gap instead of waiting or guessing. Scale depth to material risk without skipping checks. Preserve dependency and safety order; otherwise choose an appropriate verification method. Accept equivalent user or repository evidence; no other skill, named artifact, or complete lifecycle is required. Preserve source requirement and decision IDs. Bind reused evidence to relevant source versions, dirty changes, configuration, and environment; invalidate only affected claims. On continuation, reconcile task, authorization, current state, and unresolved evidence. For long work, return a compact continuation record or update an already authorized artifact; read-only skills do not persist it. Distinguish artifact readiness, verified behavior, and external-action authority. Prepare authorized work before required approval. If blocked by an instruction, cite its exact source and unresolved boundary; do not invent approval gates from caution.

Tool Routing

Do not optimize by aesthetic preference or benchmark a different workload from the reported problem. Never discard user changes, use destructive Git reset, or run uncontrolled load against production.

Evidence Rules

• Separate cold-start, warm steady-state, and saturated-load behavior when the reported problem can occur in more than one regime.
• Profile contribution and end-to-end impact separately: a hot function can improve while the user-visible metric does not.
• Treat profiler estimates, synthetic workloads, and production observations as different evidence classes and label them.
• Correctness, resource safety, and operational stability are hard constraints, not secondary metrics.

Checklist

1. Define the Problem and Protect the Workspace

• Resolve the user-visible problem, workload, environment, primary metric, overall target, minimum improvement required to keep an experiment, and hard constraints before editing.
• Confirm a measurable performance symptom and distinguish its cause from incorrect results or missing observability. Configuration, capacity, and dependencies may be valid bottlenecks; fix them only within the approved scope.
• Read repository instructions and inspect Git state, branches, uncommitted changes, ignored artifacts, and available isolation mechanisms.
• Preserve user work and isolate experiments in a safe branch or worktree when changes, benchmarks, or generated artifacts could interfere.
• Start a run-owned resource ledger with every created absolute path, worktree, process ID, cache, profile, and temporary artifact; never register pre-existing resources as cleanup targets.
• Identify correctness, security, memory, cost, compatibility, and operational constraints that no optimization may violate.
• Locate existing benchmarks, profiles, performance tests, production traces, service-level objectives, and known environmental variability.

2. Establish a Reproducible Baseline

• Use the same metric type as the observed problem: latency distribution, throughput, CPU, memory, allocation, I/O, query count, lock wait, or another direct measure.
• Make the workload representative and deterministic enough to compare, including data size, concurrency, cache state, warmup, and build mode.
• Cover the operating points that could reverse the conclusion--at minimum the reported case plus relevant data-size or concurrency boundaries--without inventing synthetic scale.
• Choose a bounded comparison budget sufficient to assess material noise; record raw results, an appropriate center/percentile, spread, failures, and environment. Report inconclusive measurements rather than repeating until a gain appears.
• When drift or noise is material, interleave or randomize baseline and candidate runs and prefer paired comparisons over one block of "before" followed by one block of "after."
• Verify that the benchmark detects an intentionally slower or obviously changed path when practical; a benchmark insensitive to behavior cannot validate optimization.
• Run relevant correctness tests before editing so pre-existing failures are not attributed to experiments.
• Stop and report BLOCKED if the problem cannot be reproduced and no trustworthy production evidence can define a safe proxy.

3. Profile and Form Hypotheses

• Profile the end-to-end path before focusing on a function, query, allocation, lock, or network call.
• Build a ranked cost map with measured contribution, call frequency, inclusive and exclusive cost where available, and affected workload.
• Trace the top costs to implementation, callers, data shape, concurrency model, configuration, and external dependencies.
• Distinguish root bottlenecks from downstream symptoms, measurement overhead, debug builds, cold starts, and one-time initialization.
• If profiling crosses services or processes whose code is in scope, align traces/correlation IDs and follow the measured downstream path; do not label an accessible internal service "external" and stop at its latency.
• Estimate profiler or instrumentation perturbation and confirm the final end-to-end result without invasive instrumentation.
• Research official runtime, framework, database, and dependency behavior only when it can confirm or reject a concrete hypothesis.
• Check existing platform and dependency capabilities before proposing custom caches, pools, schedulers, serializers, or data structures.
• Write a small ordered hypothesis set; for each state expected metric change, mechanism, affected files, risk, dependencies, and verification.
• Reject hypotheses that lack a measurable mechanism, require speculative scale, or cannot be rolled back independently.