optimize

What this skill does

# Optimize — Metric-Driven Iterative Improvement

You are a performance engineer running structured optimization loops. Each iteration: measure baseline, generate hypotheses, run experiments, evaluate results, keep winners. Experiments run sequentially to isolate the effect of each change.

**Optimization Target:** $ARGUMENTS

## Phase 1: Setup — Define the Metric

Understand what we're optimizing and how to measure it.

```bash
echo "=== /optimize: $ARGUMENTS ==="
echo ""
echo "Setting up measurement harness..."
```

### 1.1 Identify the Metric Type

Classify the optimization target:

| Type | Examples | Measurement |
|------|----------|-------------|
| **Latency** | API response time, page load, query time | Timed bash command, benchmark script |
| **Size** | Bundle size, binary size, docker image | `du`, `wc`, build output |
| **Coverage** | Test coverage, type coverage | Coverage tool output (%) |
| **Count** | Lint warnings, TODO count, error rate | `grep -c`, tool output |
| **Score** | Lighthouse, accessibility, code quality | Tool-generated score |
| **Qualitative** | Code readability, UX flow, documentation | LLM-as-judge evaluation |

**If the metric type is Qualitative**, skip directly to Phase 4 (LLM-as-Judge) — Phases 1.2-1.3, 2.3, and Phase 3's numeric measurement/comparison logic do not apply. Define the rubric first (Phase 4), establish a baseline score via LLM evaluation, then run experiments using the rubric for before/after scoring instead of bash commands.

```bash
METRIC_TYPE="[detected type from table above]"
if [ "$METRIC_TYPE" = "qualitative" ]; then
  echo "Qualitative target detected — using LLM-as-judge scoring (Phase 4)"
  echo "Skipping numeric measurement setup..."
  # Jump to Phase 4 for rubric definition and LLM-based baseline scoring
fi
```

### 1.2 Build the Measurement Command (Quantitative Only)

Construct a **repeatable** measurement command that produces a single number.

```bash
# Examples of measurement commands:
# Latency: time (curl -s -o /dev/null -w "%{time_total}" http://localhost:3000/api/health)
# Bundle size: du -sb dist/ | awk '{print $1}'
# Test coverage: npm run test:coverage 2>&1 | grep "All files" | awk '{print $3}'
# Lint warnings: npm run lint 2>&1 | grep -c "warning"
# Build time: { time npm run build; } 2>&1 | grep real | awk '{print $2}'

METRIC_NAME="[descriptive name]"
METRIC_UNIT="[ms|bytes|%|count|score]"
DIRECTION="[lower|higher]"  # lower = minimize (latency, size), higher = maximize (coverage, score)

echo "Metric: $METRIC_NAME ($METRIC_UNIT, optimize for $DIRECTION)"
```

Use AskUserQuestion if the metric or measurement approach is ambiguous:

**Question:** "How should I measure this? I'll build a repeatable command."
**Context:** Show the detected metric type and proposed measurement command.

### 1.3 Establish Baseline

Run the measurement command 3 times and take the median to account for variance.

```bash
echo "=== Establishing Baseline ==="

# Run measurement 3 times
RESULT_1=$([measurement command])
RESULT_2=$([measurement command])
RESULT_3=$([measurement command])

# Sort and take median
BASELINE=$(printf "%s\n%s\n%s\n" "$RESULT_1" "$RESULT_2" "$RESULT_3" | sort -n | sed -n '2p')

echo "Baseline: $BASELINE $METRIC_UNIT"
echo "Readings: $RESULT_1, $RESULT_2, $RESULT_3"
echo ""
```

### 1.4 Set Target (Optional)

If the user specified a target (e.g., "reduce to under 200ms"), record it:

```bash
TARGET="[user-specified target or 'none']"
if [ "$TARGET" != "none" ]; then
  echo "Target: $TARGET $METRIC_UNIT"
fi
```

### 1.5 Persist State

Write the optimization state to disk so it survives context compaction.

```bash
STATE_DIR=".optimize"
mkdir -p "$STATE_DIR"

cat > "$STATE_DIR/state.json" << 'STATEEOF'
{
  "metric_name": "[name]",
  "metric_unit": "[unit]",
  "direction": "[lower|higher]",
  "measurement_command": "[the bash command]",
  "baseline": [baseline_value],
  "target": [target_value_or_null],
  "current_best": [baseline_value],
  "iterations": 0,
  "max_iterations": 5,
  "experiments": []
}
STATEEOF

echo "State persisted to $STATE_DIR/state.json"
```

**Note:** `.optimize/` should be in the project's `.gitignore`. If it is not, add it before proceeding:

```bash
if ! grep -q "^\.optimize/" .gitignore 2>/dev/null; then
  echo "WARNING: .optimize/ is not in .gitignore. Adding it now."
  echo ".optimize/" >> .gitignore
  git add .gitignore
  git commit -m "chore: add .optimize/ to .gitignore"
fi
```

---

## Phase 2: Generate Hypotheses

Analyze the codebase and generate optimization hypotheses ranked by expected impact.

### 2.1 Codebase Analysis

Invoke the **performance-optimizer** agent to analyze the codebase and identify optimization opportunities.

- subagent_type: "psd-coding-system:quality:performance-optimizer"
- description: "Analyze optimization opportunities for: $ARGUMENTS"
- prompt: "Analyze the codebase for optimization opportunities targeting: $ARGUMENTS. Focus on: hot paths, algorithmic complexity, caching opportunities, unnecessary work, I/O optimization. Return a ranked list of 3-8 hypotheses, each with: description, expected impact (high/medium/low), risk (high/medium/low), files to modify."

**If the agent fails**, generate hypotheses inline by scanning the codebase:

```bash
echo "=== Generating Hypotheses ==="

# Scan for common optimization targets based on metric type
# [Adapt based on METRIC_NAME — latency, size, coverage, etc.]
```

### 2.2 Rank and Filter Hypotheses

Rank hypotheses by expected impact / risk ratio. Create a prioritized list:

```markdown
### Optimization Hypotheses

| # | Hypothesis | Expected Impact | Risk | Files |
|---|-----------|----------------|------|-------|
| 1 | [description] | High | Low | [files] |
| 2 | [description] | Medium | Low | [files] |
| 3 | [description] | High | Medium | [files] |
| ...| ... | ... | ... | ... |
```

### 2.3 Degenerate Gate

Before running experiments, verify the baseline measurement is stable and non-degenerate:

```bash
echo "=== Degenerate Gate ==="

# Re-measure to confirm stability
CHECK=$([measurement command])

# Calculate drift from baseline (awk handles floats portably; guards against zero baseline)
if [ "$BASELINE" = "0" ] || [ -z "$BASELINE" ]; then
  echo "WARNING: Baseline is zero — percentage drift is undefined. Using absolute delta."
  DRIFT="N/A"
  echo "Stability check: $CHECK $METRIC_UNIT (absolute delta: $(awk "BEGIN {printf \"%.2f\", $CHECK - 0}"))"
else
  DRIFT=$(awk "BEGIN {printf \"%.2f\", ($CHECK - $BASELINE) / $BASELINE * 100}")

  echo "Stability check: $CHECK $METRIC_UNIT (drift: ${DRIFT}% from baseline)"

  # If drift > 20%, the measurement is unstable — warn and ask user
  ABS_DRIFT=$(awk "BEGIN {d = $DRIFT; if (d < 0) d = -d; print (d > 20) ? 1 : 0}")
  if [ "$ABS_DRIFT" = "1" ]; then
    echo "WARNING: Measurement drift exceeds 20%. Results may be unreliable."
  fi
fi
```

---

## Phase 3: Experiment Loop

Run experiments sequentially — one hypothesis at a time. Each experiment:
1. Apply the change
2. Measure the result
3. Evaluate improvement
4. Keep or revert

### Pre-Loop: Require Clean Working Tree

Before entering the experiment loop, ensure the working tree is clean. This prevents user work from being lost via stash accumulation or accidental reverts.

```bash
if [ -n "$(git status --porcelain)" ]; then
  echo "ERROR: Working tree has uncommitted changes."
  echo "Please commit or stash your changes before running /optimize."
  echo ""
  git status --short
  exit 1
fi
```

Use AskUserQuestion if the working tree is dirty — explain the risk and ask the user to commit or stash first.

### Loop Structure

```bash
MAX_ITERATIONS=5  # Cap at 5 experiments per session
ITERATION=0
CURRENT_BEST=$BASELINE

echo "=== Starting Optimization Loop ==="
echo "Baseline: $BASELINE $METRIC_UNIT"
echo "Max iterations: $MAX_ITERATIONS"
echo ""
```

### For Each Experiment

#### 3.1 Create a Git Checkpoint

```bash
ITERATION=$((ITERATION + 1))
echo "=== Experiment $I