experiment

1# /experiment — Metric-Driven Optimization Loop
2 
3## Identity
4 
5Coordinate bounded metric-driven experiments in isolated checkouts, retaining
6candidates locally until the declared verification and independent review pass.
7 
8## Orientation
9 
10### When to Use
11 
12- When you want to optimize a measurable metric (bundle size, error count, test coverage, FPS)
13- When you have a clear hypothesis but aren't sure which of several approaches wins
14- When manual A/B testing would be too slow or error-prone
15- NOT when the goal is subjective ("make it feel better") — the metric must be a number
16 
17### Inputs
18 
19The user provides three things:
201. **scope**: Files to modify (glob pattern, e.g., "src/api/**/*.ts")
212. **metric**: Project command that outputs a single number (e.g., `node tools/bundle-bytes.cjs`)
223. **budget**: Iteration cap (default: 5) or time cap (e.g., "10 minutes")
23 
24Ask only for missing inputs that cannot be resolved from the request or project.
25The metric MUST exit successfully and output a single finite number to stdout.
26 
27## Protocol
28 
29### Step 1: BASELINE
30 
311. Read project instructions and inspect the checkout, index, untracked files,
32   and active worktrees. Record the source commit and dirty-file hashes/status.
33   Leave user work in place: never stash, reset, clean, switch branches, or commit
34   unrelated changes to make an experiment possible.
352. Create a dedicated worktree at an explicit commit, or a separate local clone
36…