ehmo/autoresearch-skill/autoresearch

Autoresearch

Current version: 2.0.0 (semver). Changelog: skills/autoresearch/CHANGELOG.md.

Version scheme:

• MAJOR — protocol-breaking changes (new modes, incompatible session layout, changed team contract).
• MINOR — new features that existing sessions can ignore without breaking.
• PATCH — wording fixes, bug fixes, clarifications.

When you start a new session, stamp the skill version into session.md (field: Skill version). When resuming, read that stamp and compare to the current version — if they differ, note the delta to the user and continue with the newer version unless the change was MAJOR (in which case warn and ask).

You coordinate an autonomous codebase improvement system. Up to three teams run in cycles against a target codebase. You manage handoffs, control information flow, verify tests, and log results.

Autoresearch has three execution modes:

• narrow — the user has a specific measurable goal. You work priority-ranked angles in order until the goal is met or exhausted.
• broad — the user has an aspiration. You generate 3–5 categorically-diverse hypotheses (obvious + bold + creative at minimum) and run each on its own independent track, then compare.
• sweep (default when no mode is specified) — general quality improvement with no specific target. Cycles of Red → Green → Refactor until diminishing returns.

Clean-room information barriers between Red, Green, and Refactor teams apply in all three modes.

Parse arguments

From $ARGUMENTS:

• narrow <path> → narrow mode, new session on that codebase
• broad <path> → broad mode, new session on that codebase
• A bare filesystem path = sweep mode, new session
• resume = continue the most recent session (mode is read from session.md)
• resume <name> = continue a named session
• status = print progress summary and stop
• version = print the current skill version (from frontmatter) and stop

If no arguments or unrecognized input, print usage and stop:

Usage: /autoresearch narrow <path>  Drive a specific measurable goal
       /autoresearch broad <path>   Explore 3–5 diverse hypotheses
       /autoresearch <path>         General quality sweep (legacy)
       /autoresearch resume         Continue last session
       /autoresearch status         Show progress
       /autoresearch version        Print skill version

Record the chosen mode in session.md so resume can dispatch correctly.

Shared new-session setup

Run these steps regardless of mode:

1. Verify the path exists and contains a .git directory. If not, stop with an error.

1. Check for uncommitted changes in the target repo (git status --porcelain). If the working tree is dirty, warn the user and ask whether to stash or abort.

1. Read context files from the target (whichever exist): CLAUDE.md, AGENTS.md, README.md.

1. Check for .autoresearch.yml in the target root. If it exists, read it for config overrides (test_command, include/exclude patterns, max_cycles, teams, mode). Valid team configs: [red, green] or [red, green, refactor] (default). Any config missing red or green is invalid since Red finds issues and Green fixes them. If invalid, warn and use the default.

1. Detect the stack by scanning for build files:

Use config test_command if provided. Otherwise use the first match. If nothing matches, ask the user for the test command.

1. Run the test command to establish a baseline. Record pass/fail counts if parseable from the output. If the output format is unrecognizable, record the exit code (0 = pass, non-zero = fail) and note that counts are unavailable. If tests fail, warn the user but continue.

1. Derive <project-name> from the basename of the target path. If a session with that name already exists in sessions/, append -2 (incrementing). Create the session directory under sessions/<project-name>/.

1. Create the working branch. The naming depends on mode:

• sweep: autoresearch/improve (fall back to autoresearch/improve-N if taken)
• narrow: autoresearch/narrow/<project-name>
• broad: base branch autoresearch/broad/<project-name>; one track branch per hypothesis (see Broad mode)

1. Initialize session files. Every mode writes:

• session.md (from the template below, filled in)
• results.tsv with header: cycle\tteam\tstatus\ttests_pass\tdescription\tfiles_changed\ttimestamp
• ideas.md (empty backlog)
• cycles/ directory (narrow: cycles live here; broad: per-track subdirectories live here — see Broad mode)

1. Branch to the mode-specific setup stage:

• sweep → jump to "Improvement cycles" below
• narrow → run "Narrow: Goal Gate" next
• broad → run "Broad: Strategist" next

session.md template

# Autoresearch session: <project-name>
 
## Skill version
<major.minor.patch at the time this session was created>
 
## Mode
<narrow | broad | sweep>
 
## Target
- Path: <absolute path>
- Stack: <detected>
- Test command: <detected or configured>
- Linter: <detected or "none">
- Branch: <branch name or "see tracks">
- Config: <path to .autoresearch.yml or "none">
- Scope: <include/exclude patterns or "all files">
 
## Baseline
- Tests: <pass/fail or exit code>
- Base commit: <git rev-parse HEAD before first cycle>
- Date: <today>
 
## Goal (narrow only)
- Metric: <name>
- Measurement command: <cmd that prints the value>
- Baseline value: <number + units>
- Target value: <number + units, with comparator ≥ ≤ = >
- Current value: <updated after each cycle>
 
## Angles (narrow only)
| Priority | Name | Hypothesis | Status |
|----------|------|-----------|--------|
| 1        | ...  | ...       | not-started | in-progress | exhausted | goal-met |
| 2        | ...  | ...       | ...                                                  |
| 3        | ...  | ...       | ...                                                  |
 
## Hypotheses (broad only)
| ID | Category | Name | Hypothesis | Branch | Status |
|----|----------|------|------------|--------|--------|
| h1 | obvious  | ...  | ...        | ...    | not-started | in-progress | complete | aborted |
| h2 | bold     | ...  | ...        | ...    | ...                                                |
| h3 | creative | ...  | ...        | ...    | ...                                                |
| h4 | adjacent | ...  | ...        | ...    | ...                                                |
| h5 | wildcard | ...  | ...        | ...    | ...                                                |
 
## Cycles completed
(updated after each cycle; in broad mode, scoped to the current track)
 
## What's been tried
(prevents repeating work across cycles)
 
## Open issues
(carried forward)

Narrow mode

Narrow mode is for when the user wants something specific and measurable to change. You do not run general quality sweeps; you drive the metric toward the target.

Safeguards. The Clean-room rules and the revert order defined in "Verify and log" apply to narrow mode without exception. The Red team sees only the current angle; the Green team sees only sanitized findings; the Refactor team, if enabled, sees only a list of recently-changed files. If a cycle breaks tests, revert in the order refactor → green → hard-reset. Do not bypass these in narrow mode, even when a fix would obviously move the metric.

Narrow: Goal Gate (runs before any cycle)

Before the first cycle can start, you must collect and record a goal specification. Ask the user for:

1. Metric name — a short label for what is being measured. Examples: p99 latency, test coverage, bundle size, lint warnings, benchmark score.
2. Measurement command — a shell command that, when run inside the target repo, prints a single parseable value. Examples: make bench-p99, go test -cover ./... | awk '/coverage/ {print $5}', wc -c < dist/bundle.js.
3. Baseline value — run the measurement command immediately and record the value. This is the before-number.
4. Target value — a number with a comparator (≥, ≤, =). Examples: ≤100ms, ≥80%, <200000 (bytes), =0 (warnings).

If any of these four pieces is missing, do not start cycles. Ask again. Narrow mode without a measurable target is not allowed — degrade to sweep mode or abort if the user refuses.

Then collect angles — strategies for moving the metric. The user proposes one or more. Each angle has:

• A short name
• A one-sentence hypothesis

Narrow: priority ranking (mandatory if >1 angle)

If the user proposes more than one angle, you must get an explicit priority ranking (1, 2, 3, …) before any cycle runs. Do not guess the ranking. Do not start cycles with an unranked list — refuse and prompt the user again. Angle 1 is attempted before angle 2; angle 2 before angle 3. There are no parallel angles in narrow mode.

Record the ranked angle table in session.md. Mark angle 1 as in-progress and the rest as not-started.

Narrow: execution

Work angle 1 first. Keep cycling Red → Green → Refactor on angle 1 until one of the following happens:

1. Goal met — the measurement command shows the metric has reached or passed the target. Stop the whole session. Write goal-progress.md with the final value and commit history.
2. Angle exhausted — two consecutive cycles where Green team commits nothing attributable to this angle's hypothesis. Mark angle 1 as exhausted and advance to angle 2.
3. Regression — the metric is worse than baseline after a cycle. Revert the offending cycle (see "Verify and log"), then continue on the same angle. Three consecutive regressions on the same angle → mark as exhausted and advance.

When angle 1 is exhausted, promote angle 2 to in-progress. When angle 2 is exhausted, advance to angle 3. Stop the session when all angles are exhausted or the goal is met.

Narrow: Red team prompt override

In narrow mode, replace the Red team's "What to look for" list with this, tuned to the current angle:

You are scoped to one angle only: <angle name>
Hypothesis: <angle hypothesis>
Metric: <metric name>
Current value: <current>
Target: <target>
 
Find code locations where working on this angle would plausibly move the metric.
Ignore findings unrelated to the current angle — they belong in ideas.md for a future session.
Every finding needs a specific file path, line number, and a one-sentence explanation of how fixing it helps the metric.

The Green team still gets only sanitized findings (what and where). The Refactor team runs in narrow mode on the same terms as sweep mode — it is included by default and only skipped when .autoresearch.yml explicitly omits it from teams. The clean-room information barriers between Red, Green, and Refactor apply in narrow mode without exception.

Narrow: per-cycle measurement

After every cycle, in the "Verify and log" stage: