dueling-autoresearch

name	dueling-autoresearch
description	Use when the user wants two approaches raced head-to-head on a single shared metric — e.g. a classical/algorithmic lane vs an ML/learned lane, or any two strategies for the same task. Each lane runs its own analysis-first research loop confined to its lane, the lanes share a scoreboard and may borrow ideas across the boundary without abandoning their identity, and a shared eval keeps the head-to-head honest; loops until interrupted, reporting the current leader. Not for improving a single approach in isolation (use a single-track research loop), and not for picking between two finished artifacts in one shot (that is a one-time comparison).
compatibility	Requires Python 3.9+
metadata	{"version":"0.1.0"}

Dueling Autoresearch Loop

Two lanes work the same objective in parallel and race the same metric — by default a classical/algorithmic lane against an ML/learned lane (the lanes are user-named). Each lane runs its own analysis-first iteration via roles/TrackAgent.md, confined to its lane. Every round both lanes post to a shared duel_log.md scoreboard and may borrow ideas across the lane boundary — but each stays in its lane. The feedback signal is the shared <metric> on a shared eval: if the classical lane wins, that is a real result. Lanes support mixed code locations — a codebase lane edits existing repo files, a sandbox lane authors its own code — and an eval-parity gate keeps the scores comparable.

You are the orchestrator: each round you advance both lanes, update the scoreboard, and keep both honest. Do not pause for permission once the loop is running.

When to use

Use this to race two genuinely different approaches on one metric and keep them honest against the same eval — classical vs learned, two model families, two query strategies. Default to spawning both lanes in parallel and letting the scoreboard drive cross-lane idea borrowing; if a lane runs dry, push it to a more radical in-lane change or to borrow a fresh idea from the log. Not for tuning a single approach (use a single-track loop), and not for a one-shot comparison of two finished things.

The cast (all in this folder):

• roles/TrackAgent.md — the per-lane researcher, instantiated once per lane.

Setup

Resolve bindings interactively. If loop.run.yaml exists in the working dir, load it, confirm the values in one line, and skip to the loop. Otherwise: on Claude Code (the AskUserQuestion tool is available) infer a likely value for each binding and present it as the recommended option; on other hosts ask each as a quoted plain-text prompt. Then write loop.run.yaml (format: examples/run.example.yaml) and confirm the values before creating any other files.

The host also decides spawn-or-degrade: on Claude Code spawn a real Agent per lane so the two run in parallel; otherwise adopt roles/TrackAgent.md inline and run the lanes sequentially.

Shared bindings (identical for both lanes — the honesty anchor):

binding	meaning	default	how to infer
<metric>	the single metric both lanes race; ground truth of the duel	—	ask; scan run logs for a printed score
<metric_direction>	minimize or maximize	—	from the metric's nature (loss vs accuracy)
<gate>	run budget unit: time or epochs	epochs	the artifact's runner
<budget>	epochs per run (or minutes if gate: time)	5	—
<sandbox_root>	where snapshots, ledgers, and the duel log live	./sandbox	—
<iter_strategy>	snapshots or branches (snapshots recommended — two lanes on one branch is simplest)	snapshots	—

Per-lane bindings (two lanes, default names classical and learned). Each lane has a code_location that decides which other fields it needs — never add code to the codebase:

field	meaning	when
name	lane name	always
code_location	codebase or sandbox	always
run_cmd	existing entrypoint to run, e.g. python train.py	if codebase
editable_files	existing repo files this lane may edit	if codebase
entry	command run from inside <sandbox_root>/<lane>/iter<N>/, e.g. python run.py	if sandbox

• codebase — the lane maps to existing code: edits its editable_files and runs run_cmd. Two codebase lanes must have non-overlapping editable_files.
• sandbox — no implementation exists and none is added to the repo: the lane authors and runs its code inside <sandbox_root>/<lane>/iter<N>/ via entry.

Typical duel on a repo with one existing model: the learned lane is codebase (edits model.py/config.yaml, runs train.py); the classical lane is sandbox (authors its own code under <sandbox_root>/classical/iter<N>/). Nothing is added to the codebase, yet the classical lane is still built and iterated.

Eval-parity gate (the honesty anchor). Before starting, confirm both lanes report <metric> on the same held-out set, computed the same way, so the scores are comparable — state how each lane emits it (e.g. both print <metric>: to their run log). If they don't match, fix it first; the duel is meaningless otherwise. If gate: time, write a run_with_timeout.sh wrapper per lane (timeout $(( <budget> * 60 )) <entry-or-run_cmd> "$@").

Initialise the sandbox (after confirmation):

<sandbox_root>/
├── duel_log.md          ← shared channel + scoreboard (## Scoreboard, ## Round log; headers only)
├── <laneA>/results.tsv  ← lane A ledger, header only
└── <laneB>/results.tsv  ← lane B ledger, header only

Each lane's per-iteration work lives in <sandbox_root>/<lane>/iter<N>/ (analysis/, results/, the run log). A codebase lane's iter dir also holds code_snapshot/ (the pre-change copy for revert); a sandbox lane's iter dir holds the lane's actual code for that iteration (a kept iteration carries forward as the next one's starting point).

The loop (duel)

Each round advances both lanes by one iteration. On Claude Code, spawn the two TrackAgents in parallel (one turn, two Agent calls); otherwise run lane A then lane B inline. A track is one analysis-first iteration confined to its lane — the 8 steps in roles/TrackAgent.md. Round 1 is each lane's baseline (a codebase lane runs unmodified; a sandbox lane authors its initial implementation in iter1/). One change per lane per round, so each metric delta is attributable.

Copy this checklist and tick items off each round:

• State — note round N; read duel_log.md (both lanes' latest posts + the scoreboard).
• Advance each lane — run a TrackAgent (roles/TrackAgent.md) per lane, given its lane bindings, the shared <metric>/<metric_direction>/<gate>/<budget>, and duel_log.md.
• Track posts — each lane appends its round entry to duel_log.md (best <metric>, one key finding, any dead end, one idea the other lane could borrow).
• Scoreboard — update ## Scoreboard: best <metric> per lane and the current leader (per <metric_direction>); optionally flag one cross-pollination suggestion for next round.
• Continue — go to the next round; never pause to ask whether to continue.

Spawn-or-degrade per lane. Where the host supports it, spawn a real isolated TrackAgent per lane (Claude Code: an Agent per lane, both launched in one turn for parallelism). Otherwise adopt roles/TrackAgent.md inline and run the lanes sequentially. Each TrackAgent is confined to its lane and returns its iteration summary to the orchestrator.

Ledger

Two ledgers: a per-lane results.tsv for each lane's experiments, and the shared duel_log.md scoreboard + round posts.

Per-lane <sandbox_root>/<lane>/results.tsv (tab-separated, never commas in free text):

iter	<metric>	status	analysis_summary	description
1	0.6320	keep	baseline; classical features, logistic head	baseline
2	0.6610	keep	added HOG features; per-class gains on textured classes	add HOG feature extractor

status ∈ {keep, discard, crash} (0.000000 for <metric> on crash).

Shared <sandbox_root>/duel_log.md — scoreboard + per-round posts:

## Scoreboard
round	classical_best	learned_best	leader
1	0.6320	0.6480	learned
2	0.6610	0.7050	learned

## Round log
### Round 2
- **classical** — best 0.6610 (this iter 0.6610). Finding: HOG helps textured classes
  (results/per_class.txt). Dead end: raw-pixel kNN plateaus. Borrow: learned's augmentation
  could expand classical's training set.
- **learned** — best 0.7050. Finding: BN fixed conv2 saturation. Dead end: dropout hurt at this
  budget. Borrow: classical's HOG features as an aux input channel.

Report the current leader (per <metric_direction>), never a final winner — a lane that is behind can still come back. Leave results.tsv, duel_log.md, and iter*/ untracked (do not commit them).

Constraints

• Never add code to the codebase. A codebase lane edits only its own <editable_files>; a sandbox lane lives entirely in <sandbox_root>/<lane>/. Lanes never touch each other's files — every other file is the evaluation ground truth.
• Stay in lane. A lane borrows ideas, never converts into the other approach — a classical lane stays classical even if it borrows a loss/target idea from the learned lane.
• Same metric, same eval. Both lanes optimize <metric> on the same held-out set computed the same way; never compare otherwise. Do not modify the evaluation/metric — it is the shared ground truth that makes the duel honest.
• One change per lane per round, so each metric delta is attributable.
• Do not install new packages or add dependencies the project lacks; helper code stays stdlib-only.
• Redirect each run's output to its lane's run log; never use tee. The sandbox is self-contained — no ../ escapes.
• Do not pause the loop to ask for direction; once running, keep both lanes iterating until manually interrupted, and report the current leader rather than declaring a final winner.