autoresearch

name	autoresearch
description	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.
triggers	["experiment","autoresearch","hypothesis","research cycle","optimize","improve metric","run experiment","test hypothesis","measure improvement","scientific loop","iteration cycle","theta wave research","baseline measurement","keep or discard","research assignment"]

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

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:

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

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:

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:

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 connectors/measure-instagram.sh
# Output: metric_value: 3.2

Quantitative (computed)

You calculate from existing data. Example: task completion rate.

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.

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.