| name | run-experiment |
| description | Forms a falsifiable hypothesis under lab/experiments/planned/ (Predictions before any run, no Results), runs the protocol, and writes up under successes/ or failures/. Use when proposing, running, or writing up an experiment, when a campaign needs a linked planned file, or before measuring a spike. |
Run an experiment
Read lab/experiments/AGENTS.md first. Do not start from lab/spikes/ after the fact.
This skill covers one experiment file: form hypothesis → freeze → run → write up. A campaign that coordinates several experiments follows .agents/skills/README.md. Informal exploration stays in lab/spikes/. Classification of unclear work starts at setup-campaign.
Form hypothesis (before any run)
The agent writes a falsifiable claim before execution. The agent does not run the method in this step. The agent does not write a ## Results section into planned/.
- Read lab/experiments/AGENTS.md and lab/experiments/templates/experiment.md.
- If the method is non-obvious, add or update
lab/experiments/algorithms/yyyy-mm-dd-slug.md.
- Copy
lab/experiments/templates/experiment.md to lab/experiments/planned/yyyy-mm-dd-slug.md.
- Set
Status: planned. Fill Question, Hypothesis, Predictions, Method.
- Predictions must be observable and include three non-empty patterns: true, false, and inconclusive. The false pattern is not “the script crashed” (that is protocol failure / inconclusive).
- Name confounders and the minimum useful experiment (smallest protocol that can discriminate true from false).
- Confirm the planned file has no
## Results heading.
- If
lab/campaigns/<slug>/ exists: add hypothesis state planned under state/hypotheses/; add a relative link in program.md; do not paste Predictions into program.md.
- Commit or otherwise freeze the planned file. Stop if Predictions are empty.
- Run:
env -u APPIMAGE -u APPDIR -u LD_LIBRARY_PATH python scripts/verify_template.py
The verifier must pass while the file is in planned/ with no Results section.
Refuse: writing Results into planned/; filling Predictions after seeing spike or trial output; backfilling from a spike. Delete a dishonest planned file if one was started. Start a new planned file only with predictions written before the next run.
Hypothesis states include planned, testing, supported, falsified, unresolved. Trial outcomes (accepted, rejected, invalid, inconclusive, crashed) are not hypothesis verdicts. Do not mix those vocabularies.
Required headings in the planned file: Question, Hypothesis, Predictions, Method, Related. No Results.
During the run
Do not edit Predictions. Store artifacts in lab/experiments/results/yyyy-mm-dd-slug/ with a README listing files. Large binaries go under ignored/experiment-artifacts/ with a pointer.
If the method must change in a way that invalidates Predictions, abandon this run: move nothing to successes; write a new planned file.
After the run (write up)
- Copy the planned body into the completed skeleton from
templates/experiment-completed.md.
- Fill Results, Verdict, Updated hypothesis. Verdict is about the claim, not “the script exited 0”.
- Move the file to
successes/ when the hypothesis is supported. Move it to failures/ when the hypothesis is falsified or the protocol failed. Delete the planned/ copy. Set Status to match the folder.
- If design should change, add an Agent Note in the same change (maintain-docs).
- Run
python scripts/verify_template.py (scrub AppImage env as above when needed).
Forbidden recoveries
Do not write Predictions after looking at Results. Delete the dishonest file and start a new planned experiment.
Examples
Read references/examples.md for three complete form-hypothesis examples (nominal, boundary refuse, different domain).
