# Autoresearch

> The analyst has assigned you a research cycle, or you have identified a metric you want to improve through systematic experimentation. You will form a hypothesis, make a targeted change, measure the outcome against a baseline, and decide whether to keep or discard the change. You repeat this loop until the metric improves or you exhaust viable hypotheses. This is not ad-hoc research — it is structured scientific iteration with a defined metric, a hypothesis, and a measurable result.

- Skill: `grandamenium/autoresearch-3` (Agent Skill)
- Install (CLI): `npx skillmds@latest add grandamenium/autoresearch-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/grandamenium/autoresearch-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: grandamenium (https://skillmd.com/u/grandamenium)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/grandamenium/autoresearch-3

---


# Autoresearch

You are a scientist. Autoresearch is how you systematically improve specific aspects of your work by running experiments, measuring results, and learning from outcomes.

## What It Is

You have research cycles assigned to you (check `experiments/config.json`). Each cycle has:
- A **metric** you are optimizing (the dependent variable)
- A **surface** you are experimenting on (the independent variable - what you change)
- A **direction** (higher or lower = better)
- A **measurement window** (how long to wait before measuring)
- A **measurement method** (how to get the metric value)

You cannot autonomously modify your own cycle configuration without direction. For your own theta-wave autoresearch cycle, configuration is managed through theta-wave SKILL.md — you CAN modify your own theta-wave parameters there. If the user asks you to modify a cycle, you can. You CAN and SHOULD run experiments within your assigned cycles.

## The Experiment Loop

When your experiment cron fires, execute these steps:

### Step 1: Gather Context
```bash
cortextos bus gather-context --agent $CTX_AGENT_NAME --format markdown
```
Read the output carefully. Pay attention to:
- What experiments have been tried before
- What was kept (these patterns work - build on them)
- What was discarded (these approaches failed - avoid repeating)
- Your current keep rate and trajectory

### Step 2: Evaluate Previous Experiment
If there is an active experiment (check `experiments/active.json`):
- Compare ALL relevant aspects: the surface changes you made, the context around those changes, and the output metric
- Measure the metric using the configured measurement method
- Run evaluate-experiment:
```bash
cortextos bus evaluate-experiment <experiment_id> <measured_value> --justification "Why this result makes sense"
```
For qualitative metrics, use `--score <1-10>` with a written justification.

### Step 3: Hypothesize
Based on accumulated learnings:
- Review what worked (keeps) and what failed (discards)
- Identify patterns - what themes appear in successful experiments?
- Consider untested approaches
- Form a specific, testable hypothesis
- Your hypothesis must be evidence-backed (cite past results or research)

**Exploit vs Explore:** If something has been kept 3+ times in a row, exploit that pattern further. If you have been discarding 3+ times, try something more radically different.

### Step 4: Create Experiment
```bash
cortextos bus create-experiment "<metric_name>" "<your hypothesis>" --surface <path> --direction <higher|lower> --window <duration>
```
If `approval_required` is true in `experiments/config.json`, you must manually create an approval before proceeding:
```bash
APPR_ID=$(cortextos bus create-approval "Run experiment: <hypothesis>" experiments "Cycle: <cycle_name>, Metric: <metric_name>, Surface: <surface>")
cortextos bus send-telegram $CTX_TELEGRAM_CHAT_ID "Approval needed to run experiment for <metric_name> — check dashboard"
# Block until approved, then continue to Step 5
```

### Step 5: Make Changes and Run
Apply your hypothesized changes to the surface file. Then:
```bash
cortextos bus run-experiment <experiment_id> "Description of what you changed"
```
This creates a git commit with your changes (the experiment commit) so they can be cleanly reverted if the experiment fails.

### Step 6: Wait
The cycle ends. Your next cron trigger picks up at Step 1, where you will evaluate this experiment.

## Measurement Methods

### Quantitative (scripted)
A script returns a number. Example: API scrape for engagement rate.
```bash
bash connectors/measure-instagram.sh
# Output: metric_value: 3.2
```

### Quantitative (computed)
You calculate from existing data. Example: task completion rate.
```bash
COMPLETED=$(cortextos bus list-tasks --agent $CTX_AGENT_NAME --status completed | jq length)
TOTAL=$(cortextos bus list-tasks --agent $CTX_AGENT_NAME | jq length)
RATE=$(echo "scale=2; $COMPLETED / $TOTAL * 100" | bc)
```

### Qualitative (subjective)
You evaluate output quality on a 1-10 scale. You MUST write a justification.
```bash
cortextos bus evaluate-experiment <id> 0 --score 7 --justification "Output is more concise and actionable than baseline, but loses some nuance"
```

### Qualitative (comparative)
You compare baseline vs experiment output side by side and score 1-10.

## Setting Up Your Own Cycle

Your theta-wave autoresearch cycle (metric: system_effectiveness) is set up during onboarding. For mid-session reference on setting up or modifying cycles, see `.claude/skills/theta-wave/SKILL.md` — that skill owns cycle management for the analyst.

## Important Rules

1. Never autonomously modify cycle config without direction. Your theta-wave cycle is the exception — manage it via theta-wave SKILL.md.
2. You MUST log learnings for EVERY experiment, including failures. Negative learnings are equally valuable.
3. You MUST respect the measurement window - do not evaluate early.
4. If approval_required is true, WAIT for approval (manual — see Step 4 above).
5. Never repeat a hypothesis that was already discarded. Find a new angle.
6. Keep experiments focused - change one thing at a time when possible.