experiment-design

name	experiment-design
description	Use when the user wants to design experiments, plan ablation studies, structure baselines, or create incremental evaluation strategies. Triggers on phrases like "design ablation", "plan experiment", "what experiments should I run", "baseline comparison", or "experiment matrix". Do not use for ablation-planner requests after main results pass result-to-claim (use ablation-planner).

Experiment Design Methodology

You are helping a researcher design rigorous experiments. Follow this methodology systematically.

Step 1: Understand the Research Question

Before designing any experiment:

• Ask what specific hypothesis or claim the experiment should support
• Identify the dependent variable (metric) and independent variables (factors)
• Clarify the baseline: what is the current best result or default configuration?

Step 2: Single-Variable Isolation

Every ablation study must change exactly ONE variable at a time. For each factor:

1. Define the factor — what is being varied (e.g., loss function, learning rate, architecture component)
2. List levels — all values this factor will take (e.g., CE, focal, VAR)
3. Fix everything else — document what stays constant (seed, data split, epochs, hardware)
4. Predict outcome — before running, state what you expect and why

Template for each ablation row:

| Run ID | Factor | Value | Fixed Config | Expected Outcome |
|--------|--------|-------|-------------|-----------------|

Step 3: Experiment Matrix

For multi-factor studies, use a structured matrix:

1. Full factorial — if factors are few (≤3) and levels are few (≤3 each)
2. Sequential elimination — if factors are many: run single-factor ablations first, then combine winners
3. Latin square — if full factorial is too expensive: sample representative combinations

Always calculate total runs before committing:

Total runs = product of all factor levels
GPU hours = total runs × hours_per_run

Step 4: Resource Estimation

For each experiment plan, estimate:

• GPU hours: runs × time_per_run (check with user's hardware)
• API costs: if using external APIs (Gemini, OpenAI), estimate tokens × price
• Wall clock time: accounting for sequential dependencies and GPU availability
• Storage: checkpoint sizes × number of runs

Flag if total cost exceeds reasonable bounds and suggest prioritization.

Step 5: Config Stub Generation

Generate configuration stubs that match the user's existing config format. Read existing configs first to match:

• File format (YAML, JSON, TOML)
• Key naming conventions
• Directory structure for outputs
• Logging/tracking integration (wandb, neptune, tensorboard)

Step 6: Execution Plan

Create a concrete execution plan:

1. Order runs by dependency (baselines first, then ablations)
2. Identify which runs can be parallelized across GPUs
3. Create a shell script or batch runner matching the project's existing patterns
4. Include checkpointing strategy for long runs

Step 7: Analysis Plan

Before running, define how results will be analyzed:

• Which metrics to compare (primary + secondary)
• Statistical significance test if applicable (paired t-test, bootstrap CI)
• How to handle failed/crashed runs
• Visualization: what plots to generate (comparison tables, bar charts, learning curves)

Verification Checkpoints

Before finalizing the experiment plan:

• Each ablation changes exactly one variable
• Baseline is clearly defined and will be run with same setup
• Resource estimate is within budget
• Config stubs match existing project format
• Analysis plan is defined before execution begins
• Seeds are fixed for reproducibility

Output Format

Always produce:

1. Experiment matrix table — all runs with their configurations
2. Resource estimate — GPU hours, API costs, storage
3. Execution script — ready-to-run commands matching project conventions
4. Analysis plan — metrics, comparisons, visualizations