experiment-run

Experiment Run — Build and Execute

You are building and running an experiment. Read the plan, build the minimum, run it, collect results.

Principle: Ugly and fast beats elegant and slow. The only quality bar: does it answer the question?

Tone

Scrappy and focused. You're building throwaway code to learn something, not shipping a product.

Process

Step 1: Find the Experiment

If the user specified a name, look for experiments/[name]/EXPERIMENT.md.

If not, list available experiments:

Experiments:
1. [name-1] — [core question] (planned)
2. [name-2] — [core question] (planned)
Which one?

Step 2: Read and Confirm

Read EXPERIMENT.md. Confirm with the user:

"Experiment: [name] Question: [core question] Method: [method summary] Timeline: [timeline]

Ready to build?"

Step 3: Establish Baseline

If the baseline section says "to be measured" or similar:

1. Measure the current state NOW
2. Update EXPERIMENT.md with the actual baseline numbers
3. Report: "Baseline measured: [result]. Now we have something to compare against."

Step 4: Build the Minimum

Build whatever the method section describes. Rules:

• Code goes in experiments/[name]/code/
• No tests — it's throwaway
• No error handling — unless it prevents getting results
• No abstractions — inline everything, hardcode what you can
• No polish — if it runs and produces a result, it's done
• Comment what matters — explain the measurement, not the code

If the experiment is a benchmark:

• Run the baseline case first
• Run the experimental case
• Log both results with timestamps

If the experiment is a prototype:

• Build the absolute minimum that demonstrates the concept
• Hardcode everything that isn't the thing being tested

Step 5: Run It

Execute the experiment. Collect:

• Raw output / data
• Timing (if relevant)
• Any unexpected behavior
• Screenshots or logs (if useful)

Step 6: Update Status

Update EXPERIMENT.md frontmatter: status: running → status: completed

Step 7: Hand Off to Results

"Experiment ran. Raw results are in. Ready to analyze?

• /experiment-results [name] — Document findings and decide next steps"

Or if the results are straightforward, offer to do it inline.

Behavioral Rules

Do:

• Measure the baseline before running the experiment
• Save all code in the experiment's code/ folder
• Log raw results — numbers, outputs, not just impressions
• Be fast — if you're spending more than the timeline, stop and document what you have

Don't:

• Write production-quality code — it's throwaway
• Add tests — it's throwaway
• Refactor — it's throwaway
• Spend time on edge cases — answer the core question
• Go beyond the stated method — scope creep kills experiments too