experiment-workflow

name	experiment-workflow
description	Run thesis experiments from ideation through publication. Use when brainstorming research questions, writing specs, executing experiments, or polishing for thesis.

Experiment Workflow

This skill covers the lifecycle of a research experiment from initial idea to thesis publication.

Workflow stages

1. Ideation — Capture and deconfuse the research question
2. Specification — Plan execution with clear success criteria
3. Execution — Implement, run, analyze (OODA loop)
4. Polishing — Prepare artifacts, code, and writeup for thesis

Agents typically work on one stage (~80% of sessions). You can proceed through multiple stages in one session, but results tend to be subpar—these are long-horizon tasks, and agents excel at medium-horizon work.

Where things live

Artifact	Location
Tracking table	packages/latex_viterbo/experiments.md
Experiment code	packages/python_viterbo/src/viterbo/experiments/<label>/
Specification	<experiment folder>/SPEC.md
Rust-only specs	packages/rust_viterbo/docs/<label>.md (rare)
Polished writeups	packages/latex_viterbo/chapters/appendix-detailed-experiments.tex
Plots/figures	packages/latex_viterbo/assets/<label>/
Data artifacts	packages/python_viterbo/data/<label>/

Polished writeups go in a single growing file (appendix-detailed-experiments.tex). Each experiment becomes a \section{<label>}. If the file gets unwieldy, we can split to folder + \input later.

Labels unify everything: the experiment folder name, thesis section label, tracking table row, and asset folder all use the same label (e.g., counterexample-hko, dimension-5-probing).

Stage 1: Ideation

Goal: Turn a vague idea into a clear, answerable research question.

Process:

1. Write down the question in plain language
2. Deconfuse: What exactly would a "yes" or "no" answer look like?
3. Identify what's already known (prior work, related experiments in the thesis)
4. Note what's still unclear or needs Jörn's input

Artifact: New row in packages/latex_viterbo/experiments.md:

| label | Ideation | The research question | Any notes |

Mark as [proposed] until Jörn approves. No folder needed yet—just the tracking entry.

Stage 2: Specification

Goal: Plan execution with enough detail that another agent could implement it.

Process:

1. Define success/failure criteria explicitly
2. Identify required inputs (data, algorithms, dependencies)
3. Sketch implementation approach
4. Estimate what artifacts will be produced
5. Note which thesis section(s) this feeds into (if known)

Artifact: Create the experiment folder and write SPEC.md:

packages/python_viterbo/src/viterbo/experiments/<label>/
└── SPEC.md

Update tracking table status to "Specified".

SPEC.md should include:

• Research question (copied from tracking table)
• Inputs: what data/code is needed
• Method: implementation approach
• Success criteria: what outcome means "it worked"
• Expected outputs: data files, plots, metrics

Stage 3: Execution

Goal: Implement and run the experiment, producing results.

This is standard work: analyze requirements, write code, run it, interpret outputs. Use the OODA loop—observe, orient, decide, act—adapting on the fly while paying attention to outer context. Most agents know how to do this given a clear spec.

Context for execution agents:

• See python-conventions skill for experiment code structure
• See rust-conventions skill if modifying algorithms
• SPEC.md in the experiment folder has success criteria

Artifact: Working code, data artifacts, preliminary results. Update tracking table status to "Executed" or "In progress".

Stage 4: Polishing

Goal: Prepare everything for thesis publication.

Process:

1. Clean up code (lint, tests, docstrings where non-obvious)
2. Finalize data artifacts with clear naming
3. Generate publication-quality plots/tables → packages/latex_viterbo/assets/<label>/
4. Write experiment section in appendix-detailed-experiments.tex with interpretation
5. Self-review against the thesis's high standards
6. Update tracking table status to "Polished" or "Complete"

Done when: Passes your self-review against thesis standards. Jörn reviews as fallback for complex interpretations or if thesis standards were misunderstood.

Abandoned / Failed / Superseded experiments

Experiments don't always succeed. When abandoning:

1. Update tracking table: status → "Abandoned" / "Failed" / "Superseded by X"
2. Clean up code: remove dead implementation, but keep a stub with:
   • The original SPEC.md (or summary of it)
   • Brief explanation of why abandoned (saves future agents time)
3. Optionally note in thesis appendix if the failure is instructive

Approval markers

Use [proposed] for agent-proposed content awaiting Jörn's review.

Critical: Never write "approved" markers without Jörn's explicit approval. Ambiguous responses ("sounds fine") do not count as approval.

Only Jörn removes [proposed] markers.

Handoff between stages

When finishing a stage:

1. Update the tracking table with current status
2. Ensure SPEC.md (if exists) reflects current state
3. Commit changes with clear message referencing the label (e.g., "counterexample-hko: complete specification")
4. If blocked or needing input, note it explicitly in SPEC.md or tracking table

[proposed]