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