When implementing or changing optimization code (samplers, objectives, and result selection), ensure algorithmic correctness, preserve sampler assumptions, and prefer explicit post-processing over ad‑hoc objective hacks. Why: Incorrect assumptions about samplers, unclear trial counting, off-by-one indexing, or hidden objective tweaks can silently break search quality or produce confusing results. The rule reduces bugs and makes behavior auditable. Checklist (practical actions): - Validate sampler constraints before changing parameter conditioning - If using multivariate TPE, avoid introducing conditional/variable-range params that the sampler does not support, or adjust sampler options (e.g., grouping) deliberately and consistently. - Example: do not move from unconditional sampling to conditional sampling without ensuring the sampler remains valid. - Compute trial counts and statuses in one clear place - Count completed trials once and use that to adjust remaining trials rather than maintaining ad-hoc "extra" counters. - Example: completed_trials = [t for t in study.trials if t.state == TrialState.COMPLETE] remaining = max(0, desired_n_trials - len(completed_trials)) - Don't change the objective to fix selection/display issues; post-process instead - Keep the objective function simple and theoretically justified. If the Pareto/front presentation shows ties or ambiguity, resolve those when selecting best trials rather than altering the objective scoring. - Example post-processing (derive Pareto front from completed trials): sorted_trials = sorted( completed_trials, key=lambda t: (t.user_attrs['refusals'], t.user_attrs['kl_divergence']) ) best = [] min_div = float('inf') for t in sorted_trials: kld = t.user_attrs['kl_divergence'] if kld < min_div: min_div = kld best.append(t) - Be explicit about indexing and distances (avoid fenceposts) - When expressing distances or ranges over indices, document whether you mean count (n) or last index (n-1). Prefer using clear names (num_layers, last_layer_index) and compute derived values using the correct base. - Example: if n = number of layers, largest index distance = n - 1; use 0.6 * (n - 1) if you intend a fraction of the index span. - Prefer simple, well-justified changes over complex heuristics - If smoothing or interpolation is proposed to "improve" optimizer behavior, require theoretical justification or strong, reproducible experimental evidence; prefer linear/simple approaches and clearly note any new tuning parameters. When to apply: any change touching sampling logic, objective computation, trial bookkeeping, or final selection of best trials. Following this guidance improves correctness, reproducibility, and debuggability of optimization code.