| name | autoresearch |
| description | Autonomous loop that optimizes a measurable metric (coverage, bundle size, lint errors) one change at a time. Use when repeated experiments can be judged by a mechanical score. |
| triggers | ["autoresearch","optimize this metric","run experiments to improve","autonomous optimization loop"] |
| category | meta |
| license | MIT |
| metadata | {"attribution":"Core patterns from autoresearch by Udit Goenka (MIT); adapted for cue","version":"1.0.0"} |
Autoresearch: Autonomous Optimization Loop
Constraint + mechanical metric + fast verification = autonomous improvement.
Run N iterations that each make one atomic change, measure a single number, and keep or discard based on the score. Git is the memory and the rollback.
When to use
- Improve a measurable metric: test coverage, bundle size, ESLint error count, Lighthouse score.
- Autonomous execution over many iterations without manual steering.
- Git-tracked experiments where you want automatic rollback on regression.
When NOT to use
| Situation | Better tool |
|---|
| Subjective goals ("make it cleaner") | just with an approved direction |
| Bug fix with a known root cause | investigate then a direct fix |
| One-shot task, no repetition | just |
| No mechanical metric to score progress | autoplan / normal flow |
Prerequisites
- A git repository with a clean working tree before starting.
- A
Verify command that prints a single number to stdout and finishes in under ~30 seconds.
Configuration
Parse from the user message. Missing required fields trigger one batched AskUserQuestion.
Required: Goal (what to improve), Scope (glob of editable files), Verify (shell command printing one number).
Optional: Guard (regression check, exit 0 = pass), Iterations (default 10), Noise (low/medium/high), Min-Delta (default 0), Direction (higher/lower, default higher).
Core protocol
See references/autonomous-loop-protocol.md for the full 8-phase spec. Key invariants:
- One atomic change per iteration. Test: can you describe it in one sentence with no "and"?
- Commit before verify. Git is memory, not just a safety net.
- Guard files are read-only. Never edit files in the guard command's scope.
- Prefer
git revert over git reset to preserve history.
Results logging
Each iteration appends a TSV row to loop-results.tsv in the working directory: iteration, commit, metric, delta, status (baseline/keep/discard), description. Full schema in references/results-logging.md.
Stuck detection
- 5 consecutive discards: analyze patterns, shift strategy (different files or approach).
- 10 consecutive discards: stop, report findings, surface to the user.
References
references/autonomous-loop-protocol.md full 8-phase loop, decision matrix, anti-patternsreferences/git-memory-pattern.md git as cross-iteration memory, revert vs resetreferences/guard-and-noise.md regression guard pattern, noise-aware verificationreferences/results-logging.md TSV format and progressive summariesreferences/metric-library.md common verify commands by domain
Example
Goal: Increase test coverage in src/utils from ~60% to 80%
Scope: src/utils/**/*.ts, tests/utils/**/*.test.ts
Verify: npx jest tests/utils --coverage --coverageReporters=json-summary 2>/dev/null | node -e "console.log(require('./coverage-summary.json').total.lines.pct)"
Guard: npx tsc --noEmit && npx jest --passWithNoTests
Iterations: 15
Direction: higher
The loop commits each kept change, reverts each regression, and logs every iteration to loop-results.tsv.
Limitations
Cannot optimize subjective goals, cannot edit files outside Scope or files the Guard reads, cannot guarantee improvement (metrics have ceilings), and runs sequentially by design so each iteration learns from the last.
