/codex-autoresearch

name: codex-autoresearch
description: Run or resume a measured improvement loop in a local project. Use for benchmark-driven optimization, qualitative quality-gap research, packet logging, dashboard readouts, recovery, and review-branch finalization backed by autoresearch session files.

Codex Autoresearch

Turn an improvement request into a measured, resumable loop. Report the metric, decision, evidence, next action, and real publication state. Do not replace them with a generic claim that the project is "better."

setup -> doctor -> next -> log -> state -> finalize-preview

Use this as the only Codex-facing Autoresearch skill. Do not route to retired subskills, slash commands, or MCP surfaces.

Establish the working truth

1. Identify the repository or child package that owns the work. 2. Run `git status --short --branch`; preserve unrelated changes. 3. When changing Autoresearch itself, use the checkout in this repository:

• wrapper root: `node plugins/codex-autoresearch/scripts/autoresearch.mjs ...`
• package root: `node scripts/autoresearch.mjs ...`

4. Treat source and installed-plugin behavior as different until their version and built-entrypoint fingerprint match.

Start or resume

For a new session:

1. Get the goal, benchmark, primary metric, direction, correctness checks, editable scope, and any real budget. 2. Use `prompt-plan` or `setup-plan` when one of those is unclear. Both are read-only. 3. Run `setup` only after the contract is clear enough to create files. 4. Configure `commitPaths` before a keep may commit source changes. 5. Run `doctor --cwd <project> --check-benchmark --explain` before trusting the first packet. 6. Record the baseline with `next`, then `log --from-last --status measure`.

For an existing session:

1. Read [loop operations](references/loop-operations.md). 2. Read `autoresearch.md`, `autoresearch.jsonl`, `autoresearch.ideas.md`, and the active `autoresearch.research/<slug>/` folder when present. 3. Run `state --report`, `recommend-next --compact --operator-checklist`, and `doctor --explain`. These defaults are bounded and share one `resolvedDecision`; use `state --json-full` or `doctor --json-full` only for complete machine diagnostics. 4. Keep `goalFrame.authoritativeGoal` authoritative unless the user deliberately replaces it. If a new request would change the benchmark, metric, edit scope, or final claim, treat it as a possible replacement and resolve that choice before packet work. 5. Follow the printed blocker or command. If the CLI, report, and dashboard disagree, stop mutation and diagnose the shared state.

Happy path from the package root:

node scripts/autoresearch.mjs setup --cwd <project> --name "<session>" --metric-name <metric> --direction lower --benchmark-command "<command>" --checks-command "<checks>"
node scripts/autoresearch.mjs config --cwd <project> --commit-paths "<editable-paths>"
node scripts/autoresearch.mjs doctor --cwd <project> --check-benchmark --explain
node scripts/autoresearch.mjs next --cwd <project>
node scripts/autoresearch.mjs log --cwd <project> --from-last --status measure --description "Baseline measurement"
node scripts/autoresearch.mjs state --cwd <project> --report

After the baseline, implement one bounded hypothesis inside the configured paths, then run and log one packet:

node scripts/autoresearch.mjs next --cwd <project>
node scripts/autoresearch.mjs log --cwd <project> --from-last --status keep --description "<what changed>" --asi-json-file <path>
node scripts/autoresearch.mjs state --cwd <project> --report

The ASI file must contain the real hypothesis, evidence, rollback reason when rejected, and next action. Use `discard`, `crash`, or `checks_failed` instead of `keep` when the evidence requires it. Run `finalize-preview` only when canonical state routes to finalization.

Run one packet at a time

Use `next` for a reusable packet. Use `benchmark-inspect` for a bounded diagnostic probe; the old `run` name fails fast with that migration and is scheduled for removal after 2026-10-01.

After `next`:

1. Inspect the metric, checks, artifacts, diff, and Git state. 2. Log with `--from-last`; do not copy parsed metrics back into the command. 3. Add a structured experiment note (ASI) with the hypothesis, evidence, rollback reason for rejected work, and useful next action. Use `--asi-json-file <path>` when inline JSON would be fragile in the current shell. 4. Read the returned continuation before doing anything else.

When accepted work was committed outside Autoresearch, verify the commit and log the keep with `--commit <hash>` so finalization retains real commit evidence.

| Status | Use it for | | --- | --- | | `measure` | Baselines, no-change checks, environment probes, and diagnostics. Never stage, commit, revert, or finalize it. | | `keep` | A finite primary metric, passing required checks, and a change worth preserving inside safe Git scope. | | `discard` | A finite metric and a change not worth keeping; logging may clean the configured or explicit experiment paths. | | `crash` | A benchmark that failed before usable metric evidence existed. Do not invent a sentinel value; logging may clean the configured or explicit experiment paths. | | `checks_failed` | A metric exists, but the required correctness proof failed; logging may clean the configured or explicit experiment paths. |

Obey these brakes:

• Keep packet processes on the default minimal environment. Use `--packet-env-mode inherit` only when the benchmark genuinely needs the caller's full environment.
• Treat `termination_failed` as a hard stop. Preserve partial packet evidence, verify the reported PID and descendants are absent, then remove only the retained progress marker before another `next`.
• Treat typed `process_lifecycle` blockers as process truth: verify absence before recording a later terminal row. Never infer active residue from historical prose, and never repair a malform