| name | evolve |
| description | Goal-pursuit loop: measure, diagnose, experiment, verify, compare, and iterate against a measurable target. Triggers: evolve, optimize, make this better, push to target. |
Evolve
Use this when there is a measurable target and repeated changes can move it.
Do not use it for vague quality polish, red CI, or one-off analysis.
Start
- Read existing
.evolve/ state if present.
- Define the target metric, baseline, acceptable variance, and user value connection.
- Run the smallest real baseline before changing anything.
- If no metric exists, build or choose one first.
Loop
- Diagnose the largest measured gap.
- Pick the top bet. If the next lever is obvious, propose one hypothesis with a mechanism and a falsifiable result. If more than one plausible lever exists — or you haven't surveyed how the world beats this ceiling — run
/hypothesize first and pull the top-ranked bet from its portfolio.
- Make the smallest change that tests the hypothesis.
- Re-run the exact baseline check plus any needed regression checks.
- Compare against baseline with enough samples for the claim.
- Keep, revert, or iterate based on the measured result.
- Persist experiment rows, progress, and next dispatch in
.evolve/.
Rules
- No metric gaming; user-visible quality wins over score movement.
- No broad rewrites until smaller hypotheses fail.
- Treat surprising lifts, nulls, and too-clean results as suspect until raw data explains them.
- Stop after five rounds or when the next step needs a different skill.
Use references/full-reference.md for statistical details, structured-hypothesis mode, and state schemas.
Use references/deterministic-loop.md for the tamper-proof measure.sh harness, auto-revert discipline, the ≥2× noise-floor keep-check, and the resumable playbook — the loop that makes evolve safe to run unattended for hours.
Then consider
hypothesize when "what to try next" is no longer obvious — build a researched, ranked portfolio instead of guessing one lever.meta-harness or pursue after repeated measured plateaus.autopsy for surprising or null results.polish when the metric is fine but quality still needs fixed-rubric cleanup.
