Auto Research Loop — Autonomous Iteration Engine

Invocation

/auto-research-loop [PROMPT] [FLAGS]

"${CLAUDE_PLUGIN_ROOT}/scripts/setup-auto-research-loop.sh" $ARGUMENTS

/auto-research-loop-plan

${CLAUDE_PLUGIN_ROOT}/skills/auto-research-loop/references/plan-workflow.md

1. Capture goal
2. Analyze codebase context
3. Define scope (which files to modify)
4. Define metric (must be mechanical — a command that outputs a number)
5. Define direction (higher or lower is better)
6. Define verify command (dry-run it to confirm it works)
7. Confirm and launch — output a ready-to-paste

   /auto-research-loop

   command

Two Modes

--metric

--verify

git revert

autoresearch-results.tsv

IMPLEMENTATION_PLAN.md

The Loop

LOOP:
  0. Scratchpad: READ .claude/auto-research-loop-scratchpad.md
  1. Review: State + git log + results/plan
  2. Ideate: Fix crashes > exploit wins > explore > simplify > radical
  3. Modify: ONE focused change
  4. Commit: git commit BEFORE verification
  5. Verify: Metric command (metric) or gate commands (task)
  6. Decide:
     Metric: IMPROVED -> keep. WORSE -> git reset --hard HEAD~1
     Task: Gates pass + promise true -> exit. Else -> continue
  7. Log: Results TSV (metric) or update plan (task)
  8. Scratchpad: UPDATE before exit
  9. Repeat

${CLAUDE_PLUGIN_ROOT}/skills/auto-research-loop/references/autonomous-loop-protocol.md

Critical Rules

1. NEVER STOP — loop until interrupted, max iterations, or promise met
2. One change per iteration — atomic, attributable
3. Mechanical verification only — no subjective judgment
4. Simplicity wins — equal results + less code = KEEP
5. Git is memory — commit before verify, revert on failure
6. Scratchpad is mandatory — read at start, update before exit

Domain Adaptation

pytest --cov | grep TOTAL

src/**/*.py

npm run build | grep size

src/**/*.ts

uv run train.py | grep val_bpb

train.py

npm run bench | grep p95

rm .claude/auto-research-loop.local.md