refactor-for-optimize

Files (3)

• README.md
• SKILL.md
• evals.json · evals/

SKILL.md (first lines)

# Refactor for Optimization

## Overview

Improve the performance profile of working code — without changing what it does. The goal is not fewer lines or cleaner structure — it's measurably faster or lower-memory execution on the paths that matter. Every change must pass: "Is this demonstrably faster or cheaper than before, with all tests still green?"

## When to Use

- In the REFACTOR phase of `test-driven-development`, when the developer identifies a hot path needing improvement
- When profiling reveals a specific function or loop is the bottleneck
- When algorithmic complexity is clearly wrong (O(n²) scan of a list that should be an O(1) set lookup)
- When unnecessary I/O occurs inside a loop (repeated file reads, N+1 database queries, repeated computations)
- When memory pressure is measurable and the cause is identifiable

**When NOT to use:**

- You haven't measured — optimize only where profiling or reasoning confirms the bottleneck
- The code isn't correct yet — correctness first, performance second
- The issue is naming, nesting, or structural complexity — use `refactor-for-clarity` instead
- The issue is duplication or dead code — use `refactor-for-reuse` instead
- You're about to rewrite the module entirely — wait; optimizing throwaway code wastes effort
- The "optimization" trades correctness for speed — never acceptable

## The Four Principles

### 1. Preserve Behavior Exactly

Don't change what the code does — only how fast or efficiently it does it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical.

```
ASK BEFORE EVERY CHANGE:
→ Does this produce the same output for every input?
→ Does this maintain the same error behavior?
→ Does this preserve the same side effects and ordering?
→ Do all existing tests still pass without modification?
```

### 2. Measure Before and After

Guessing where the bottleneck is causes more harm than the original problem. Optimize only where you can demonstrate a measurable cost.

```
BEFORE optimizing:
- Profile to identify the actual hot path (cProfile, py-spy, timeit)
- Name the specific bottleneck — a function, a loop, a query — not "it feels slow"
- Establish a baseline: what does it cost now?

AFTER optimizing:
- Verify the change is faster on realistic data, not synthetic micro-benchmarks
- Confirm the improvement is in the hot path, not in code that's rarely executed
```

If profiling isn't available, state the complexity change explicitly (e.g., "O(n²) → O(n)") and explain why it matters at the expected input scale.

### 3. Algorithmic Over Micro-Optimization

An O(n log n) algorithm beats a hand-tuned O(n²) algorithm at any meaningful scale. Fix the algorithm before tuning constants.

```
PRIORITY ORDER:
1. Algorithmic complexity   (O(n²) → O(n log n) → O(n))
2. Data structure selection (list scan → set/dict lookup)
3. I/O reduction            (N+1 → batch, redundant reads → cache)
4. Memory reduction         (materializing full list → generator)
5. Constant-factor tuning   (only when 1–4 are exhausted)
```

Micro-optimizations (avoiding a function call, caching an attribute lookup, reordering branches) are rarely worth the readability cost unless 1–4 have been exhausted.

### 4. Keep the Code Maintainable

A 10% speedup that makes the code unreadable is usually not worth it. If an optimization makes the code harder to follow, add a short comment explaining why — or choose the cleaner, slightly-slower implementation.

The exception: when the hot path is a genuine bottleneck and the faster version is the idiomatic form (e.g., set membership check vs. list scan), take it — it's both clearer and faster.

## Working with the Other Refactoring Skills

The three refactoring skills run in order: **clarity → reuse → optimize**. Each assumes the previous one's work is correct and load-bearing.

**Treat prior clarity and reuse improvements as non-negotiable by default.** This means:

- Do not inline extracted helpers just because function calls have overhead. In Python, that overhead is negligible — and the profiler will tell you if it isn't.
- Do not rename clear, descriptive variables back to terse forms for "speed."
- Do not break DRY abstractions to repeat logic in multiple hot paths.

**The correct action when the hot path is inside an extracted helper:** optimize the *body* of that helper, not its existence. If `_get_active_rows()` is slow, fix what it does internally — don't dissolve it back into its callers.

**When the trade-off is genuinely unavoidable** — profiling confirms the abstraction itself is the bottleneck — you may inline or restructure, but:

1. The profiler result is the justification, not an opinion.
2. Add a comment explaining why the less-obvious form is necessary: `# Inlined from _get_active_rows — profiler shows call overhead is 40% of hot path at 10k ticks/s`.
3. Flag the change explicitly in the commit message so the next developer understands the trade-off.

**The tie-breaker:** measured performance gain must outweigh the readability cost. A sub-1% gain on a cold path does not justify undoing a good extraction. If you cannot measure the gain, do not make the trade.

## The Refactoring Process

### Step 1: Verify Test Coverage

Before touching anything, confirm the code you're about to optimize is covered by tests. Tests are the only proof that behavior is preserved after optimization.

If coverage is missing: invoke **`test-driven-development`** to write characterization tests first — tests that pin the current behavior before any performance changes begin. Commit them before proceeding.

### Step 2: Understand Before Touching (Chesterton's Fence)

Before changing a data structure or algorithm, understand why the original was chosen.

```
BEFORE OPTIMIZING, ANSWER:
- What is this code's responsibility?
- What calls it? What data does it receive, and how large does that data get?
- Why might it have been written this way? (correctness constraint? platform limit? historical reason?)
- Check git blame: was this a deliberate choice or just the first-pass implementation?
```

If you can't answer these, you're not ready to optimize. Read more context first.

### Step 3: Identify the Hot Path

From eyalgo/kensaiapp, MIT.

More from eyalgo/kensaiapp