| name | vc:autoresearch |
| description | Autonomous iterative optimization loop for measurable metrics like coverage, performance, or bundle size. Use when repeated experiments can be judged by a mechanical score. |
| argument-hint | [Goal/Metric description] or inline config block |
| metadata | {"author":"claudekit","attribution":"Core patterns adapted from autoresearch by Udit Goenka (MIT)","license":"MIT","version":"1.0.0"} |
vc:autoresearch — Autonomous Optimization Loop
Constraint + Mechanical Metric + Fast Verification = Autonomous Improvement
When to Use
- Improve a measurable metric (test coverage, bundle size, ESLint errors, Lighthouse score, etc.)
- Autonomous execution over N iterations without manual intervention
- Git-tracked experiments where you want rollback on regression
- Exploring a search space of code changes with consistent evaluation
When NOT to Use
| Situation | Better Tool |
|---|
| Subjective goals ("make it cleaner") | execute-agent with an approved plan |
| Bug fixing with known root cause | debugger + execute-agent |
| One-shot tasks, no repetition needed | execute-agent |
| No mechanical metric to measure progress | normal RIPER flow instead of autoresearch |
| Files outside a defined scope | manual approach |
Configuration Format
Parsed from user message. Missing required fields trigger a batched AskUserQuestion.
Required
| Field | Description | Example |
|---|
Goal | Human description of what to improve | "Increase test coverage in src/utils" |
Scope | Glob pattern(s) for editable files | "src/utils/**/*.ts" |
Verify | Shell command that outputs a single number | "npx jest --coverage --json | jq '.coverageMap | .. | .s? | to_entries | map(.value) | (map(select(.>0)) | length) / length * 100' | tail -1" |
Optional
| Field | Default | Description |
|---|
Guard | none | Regression check command (exit 0 = pass) |
Iterations | 10 | Maximum iterations to run |
Noise | medium | Tolerance for metric variance: low / medium / high |
Min-Delta | 0 | Minimum improvement to count as progress |
Direction | higher | Whether higher or lower metric value is better |
Interactive Setup
When required fields are missing, ask all at once:
AskUserQuestion({
questions: [
{ question: "What metric do you want to improve? (e.g. 'test coverage in src/utils')", field: "Goal" },
{ question: "Which files may be edited? (glob, e.g. 'src/utils/**/*.ts')", field: "Scope" },
{ question: "Verify command — must print a single number to stdout", field: "Verify" },
{ question: "Guard command for regression check? (optional, press Enter to skip)", field: "Guard" }
]
})
Core Protocol
See references/autonomous-loop-protocol.md for the full 8-phase specification.
Key invariants:
- ONE atomic change per iteration — atomicity test: can you describe it in one sentence without "and"?
- Commit BEFORE verify — git is memory, not a safety net
- Guard files are read-only — never modify files in guard command's scope
- Prefer
git revert over git reset — preserve history
Results Logging
Each iteration appends a TSV line to loop-results.tsv in the working directory:
iteration commit metric delta status description
0 a1b2c3d 80.0 - baseline initial measurement
1 e4f5a6b 82.4 +2.4 keep add null checks to parser.ts
2 - 81.9 -0.5 discard extract helper function
See references/autonomous-loop-protocol.md — Phase 7 for full schema.
Stuck Detection
| Condition | Action |
|---|
| 5 consecutive discards | Analyze patterns → shift strategy (different files, different approach) |
| 10 consecutive discards | STOP — report findings, surface to user |
Example Invocations
1. Increase test coverage
/vc:autoresearch
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 "const d=require('./coverage-summary.json');console.log(d.total.lines.pct)"
Guard: npx tsc --noEmit && npx jest --passWithNoTests
Iterations: 15
Direction: higher
2. Reduce bundle size
/vc:autoresearch
Goal: Reduce main bundle size below 200KB
Scope: src/**/*.ts, src/**/*.tsx
Verify: npx vite build 2>/dev/null | grep "dist/index" | awk '{print $2}' | sed 's/kB//'
Guard: npx tsc --noEmit
Direction: lower
Min-Delta: 0.5
3. Eliminate ESLint errors
/vc:autoresearch
Goal: Drive ESLint error count to zero in src/api
Scope: src/api/**/*.ts
Verify: npx eslint src/api --format=json 2>/dev/null | node -e "const r=require('/dev/stdin');console.log(r.reduce((a,f)=>a+f.errorCount,0))" || echo 999
Direction: lower
Iterations: 20
Limitations (Honest)
- Cannot optimize subjective or aesthetic goals
- Cannot modify files outside the declared
Scope
- Cannot modify files referenced by the
Guard command
- Cannot guarantee improvement — some metrics have hard ceilings
- Requires a git repository with a clean working tree before starting
Verify command must complete in < 30 seconds (otherwise loop is impractical)- Does not parallelize iterations — sequential by design (each iteration learns from the last)
References
