/autoresearch

name: autoresearch
description: "Autonomous iteration loop: modify, verify, keep/discard against any metric"
version: 2.3.0

Autoresearch — Autonomous Goal-directed Iteration

Safety Invariants (all subcommands)

• Never push, publish, or deploy without explicit user approval.
• Bounded by default. Override with `Iterations: unlimited`.
• All results logged to `autoresearch/{subcommand}-{YYMMDD}-{HHMM}/` directory.
• Chain handoff via `handoff.json`. Evals reads `*-results.tsv`.

Dispatch (bare `/autoresearch`)

Parse the invocation in this order:

| Condition | Mode | |---|---| | `Metric:` or `Verify:` present | **Classic** — existing metric loop, unchanged | | Free-form natural-language goal, no metric/verify | **Orchestrator** — see Orchestrator section | | Nothing | **Setup wizard** — interactive config builder | | `--classic` flag | Force Classic regardless of goal text | | `--auto` flag | Force Orchestrator regardless of goal text |

Print a banner on every invocation: `[autoresearch] mode: classic | orchestrator | wizard`.

Subcommands

| Command | Does | Default Iterations | |---|---|---| | `/autoresearch` | Iterate against a metric: modify → verify → keep/discard | 25 | | `/autoresearch:plan` | Convert a goal into validated Scope, Metric, Verify config | N/A | | `/autoresearch:debug` | Hunt bugs: hypothesize → test → falsify → repeat | 15 | | `/autoresearch:fix` | Crush errors one-by-one until zero remain | 20 | | `/autoresearch:security` | STRIDE + OWASP audit with red-team personas | 15 | | `/autoresearch:ship` | Ship through 8 phases: checklist → dry-run → deploy → verify | N/A | | `/autoresearch:scenario` | Generate edge cases across 12 dimensions | 20 | | `/autoresearch:predict` | 5 expert personas debate before implementation | N/A | | `/autoresearch:learn` | Scout codebase → generate docs or wiki → validate → fix loop | 10 | | `/autoresearch:reason` | Adversarial debate with blind judges until convergence | 8 | | `/autoresearch:probe` | 8 personas interrogate requirements until saturation | 15 | | `/autoresearch:improve` | Research ICP challenges, discover improvements, generate PRDs | 15 | | `/autoresearch:evals` | Analyze iteration results: trends, plateaus, regressions | N/A | | `/autoresearch:regression` | Regression stability gate: baseline vs candidate, verdict STABLE/UNSTABLE | N/A |

Subcommand routing

To run a subcommand yourself (an orchestrator hop or a `--chain` target), Read its protocol file and follow it: `../../commands/autoresearch/<name>.md` (relative to this skill's directory), or `../../commands/autoresearch.md` for the classic loop. The commands are user-typed only, so the model loads them from here instead of invoking them.

Universal Flags

| Flag | Applies To | Purpose | |---|---|---| | `Iterations: N` | All looping | Set iteration count | | `Iterations: unlimited` | All looping | Opt-in unbounded | | `--evals` | All looping | Mid-loop checkpoints + final summary | | `--evals-interval N` | All looping | Override checkpoint frequency | | `--chain <targets>` | All | Sequential handoff after completion | | `--<subcommand>` | All | Shorthand for `--chain <subcommand>` | | `--dry-run` | Orchestrator | Print derived config + planned pipeline; no execution | | `--max-cycles N` | Orchestrator | Hard ceiling on orchestration cycles (default 50) | | `--classic` | Bare `/autoresearch` | Force Classic metric-loop mode | | `--auto` | Bare `/autoresearch` | Force Orchestrator mode | | `--no-fork` | Metric loops | Disable fork-and-flush rounds | | `Forks: K` | Metric loops | Branches per fork-and-flush round (default 4; 2 when Verify is slow or uses a shared resource) | | `Guided: R` | Metric loops | Fraction of fork branches given an Advisor-assigned experiment (default 0.5; 0 = all random) |

Getting Unstuck: Fork-and-Flush

Metric loops run fork-and-flush rounds on a fixed schedule: at 33% and 66% of the budget, plus early when 5 iterations pass with no `keep`. A round forks K fresh-context branches from the best commit so far, runs each for a small budget, and keeps the winner. A fresh context means the files and results log only, with none of the leader's reasoning. Half the branches (by default) are random and pick their own ideas; the other half are guided, each given one distinct experiment by a stateless Advisor that reads the results log. Protocol: `references/fork-and-flush.md` (arXiv:2610.07447, arXiv:2610.07625).

Orchestrator

Activated when a plain-language goal is given without `Metric:`/`Verify:`. Classifies the goal into a **Goal archetype** — see `references/orchestrator-routing.md` for the archetype table and router decision table.

Resolve every `scripts/...` path below relative to this installed skill directory, never relative to the caller's working directory.

For performance, latency, throughput, runtime, CPU, memory, allocations, binary size, power, energy, bandwidth, or compute-cost goals, read `references/behavior-preserving-optimization.md`. The working metric ranks candidates; independent behavior evidence decides whether a candidate survives.

**Two modes based on archetype:**

• **Orchestration loop** — predicate-bearing archetypes (ship-ready, optimize-metric, fix-broken, harden, build-feature, explore). Goal has a mechanical Success predicate; the loop runs until that predicate is met.
• **Single-pass dispatch** — subjective/terminal archetypes (document, what-to-build, decide-design). Routes once to the fitting subcommand (learn / improve / reason), lets it self-terminate, then reports. No loop, no Plateau, no ship gate.

Orchestration Loop Steps

Backed by `scripts/orchestrate.sh` (deterministic seam — all routing logic lives there). Subcommands exposed: `classify`, `next-hop`, `units`, `plateau`, `screen-cmd`, `verdict`, `validate-state`, `screen-state-predicate`.

1. **Classify** — `scripts/orchestrate.sh classify "<goal>"` → archetype label + mode. 2. **Derive predicate** — reuse `plan` log