vc:autoresearch

# 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`](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`](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

- [`references/autonomous-loop-protocol.md`](references/autonomous-loop-protocol.md) — Full 8-phase loop spec, decision matrix, anti-patterns
- [`references/git-memory-pattern.md`](references/git-memory-pattern.md) — Git as cross-iteration memory, revert vs reset, commit conventions
- [`references/guard-and-noise.md`](references/guard-and-noise.md) — Guard pattern for regression prevention, noise-aware verification
- [`references/results-logging.md`](references/results-logging.md) — TSV format spec, progressive summaries
- [`references/metric-library.md`](references/metric-library.md) — Common verify commands by domain