Use when the user wants to autonomously improve a measurable metric through iterative experimentation with git-based checkpointing and automatic rollback.
Use when the user wants to autonomously improve a measurable metric through iterative experimentation with git-based checkpointing and automatic rollback.
Do NOT proceed with uncommitted changes. The experiment loop rolls back failed experiments by resetting commits — uncommitted work WILL be lost. Stash or commit first.
---
## Context
Goal:
goal
Metric command:
command
Target:
target
(direction:
min|max
)
Max experiments:
max
Current experiment:
0
Best value:
pending
Update at each experiment iteration. Delete when optimization completes or max experiments reached.
Process
1. Pre-Flight
Run verify-clean-git-state micro-component. Confirm:
Working tree is clean (no uncommitted changes)
On a feature branch (not main/master)
Git is available
2. Baseline Measurement
Run the metric command and parse the current value:
# Run the user's metric command
RESULT=$(<metric-command>)
Parse a numeric value from the output. If parsing fails, show the raw output and ask the user to refine the --metric command.
Record baseline:
docs/sessions/.optimization-log.tsv:
commit metric_value delta status description lines_added lines_removed
<hash> <value> 0 baseline Starting point 0 0
LOOP (experiment = 1 to max):
3a. Analyze → 3b. Implement → 3c. Commit → 3d. Measure → 3e. Decide → 3f. Log
EXIT when:
- Target reached
- Max experiments exhausted
- 3 consecutive experiments with no improvement (diminishing returns)
- No more improvement ideas identified
3a. Analyze & Propose
Study the codebase for the next improvement opportunity. Use grep-first-explore to find relevant code.
Consider:
What specific change could move the metric toward the target?
Can this be achieved by removing or simplifying code? (Prefer this)
What's the expected impact on the metric?
What's the risk of regression?
Simplicity preference: If two approaches could achieve similar metric improvement, prefer the one that removes code over the one that adds code. Simpler solutions are more maintainable and less likely to introduce bugs.
Print a one-line proposal before implementing:
Experiment <N>: <brief description of the change>
3b. Implement
Make the code change. Keep changes focused — one idea per experiment. Do NOT combine multiple unrelated changes in a single experiment (makes it impossible to attribute metric movement).
3c. Commit (Checkpoint)
Stage and commit the change as an experiment checkpoint:
git add -A
git commit -m "experiment: <brief description>"
This commit exists so we can cleanly rollback if the metric regresses.
3d. Measure
Run the metric command again. Parse the new value.
Crash handling: If the metric command fails (non-zero exit, no parseable output):
Read the last 50 lines of output for error diagnosis
Attempt ONE fix (typo, missing import, syntax error)
If fix works: re-measure
If fix fails: mark as crash, rollback, continue to next experiment
# If command fails or output isn't parseable:
git reset --soft HEAD~1 # Undo the experiment commit
git restore . # Discard the experiment's changes# Log as crash, continue loop
3e. Decide: Keep or Discard
Compare new metric value against the best value so far:
IF (direction == max AND new_value > best_value) OR
(direction == min AND new_value < best_value):
→ KEEP: Branch advances. Update best_value.
ELSE:
→ DISCARD: git reset --soft HEAD~1 && git restore .
Important: Compare against best value, not baseline. The frontier only advances.
Print decision:
Experiment <N>: <description>
Result: <new_value> (was: <best_value>, delta: <change>)
Decision: KEEP ✓ / DISCARD ✗
[If KEEP: New best: <new_value>, gap to target: <remaining>]
Git safety: Every experiment is a commit. Discards use git reset --soft HEAD~1 && git restore . (safe alternatives to blocked git reset --hard). Only the latest uncommitted experiment can be lost on crash — all previous kept experiments are safe in git history.
Working tree guard: Hard gate prevents starting with uncommitted changes.
Crash isolation: Failed metric commands trigger at most one fix attempt before rollback.
Diminishing returns: Auto-stop after 3+ consecutive failures prevents infinite loops.
Branch protection: Pre-flight checks refuse to run on main/master.
Max cap: Default 20 experiments, configurable up to any limit.
When to Use
Improving test coverage toward a target percentage
Reducing bundle size, build time, or binary size
Eliminating lint warnings or type errors
Optimizing benchmark scores (latency, throughput)
Any task with a clear numeric metric and a target value
When NOT to Use
Tasks without a measurable, command-line-accessible metric
During story-cycle execution (use story-cycle's own phases)
On main/master branch (create a feature branch first)
Relationship to Other Skills
/refine-loop — Criteria-based iteration (subjective). Use /optimize when you have a measurable metric; use /refine-loop when quality is assessed by inspection.
/story-cycle — Story delivery workflow. /optimize is a standalone tool for metric improvement, not part of the sprint workflow.
/undo-work — Manual rollback. /optimize handles its own rollback automatically via git checkpoint/reset.
