# Experiment Roadmap: [TITLE]

> **How to use this template:** Run `/design-experiment` and Claude will fill
> this in based on your spec. Each phase has checkpoints — complete them in order.

---

## Phase 1: Infrastructure Validation
**Goal:** Confirm FABRIC has the resources you need.

- [ ] Check site availability with `fabric_list_sites` or `fabric_find_sites`
- [ ] Verify required hardware (GPU/FPGA/SmartNIC) is available
- [ ] Confirm project quota supports the planned node count
- [ ] Test deploying a single node to validate image and site selection

**Checkpoint:** A single node deploys to StableOK and SSH works.

### Walkthrough Questions
> 1. "What's the most critical resource to validate first?"
> 2. "Do you have a fallback if your preferred site is full?"

---

## Phase 2: Software Setup
**Goal:** All required software installs and configures correctly.

- [ ] Write `tools/setup-node.sh` (or role-specific scripts)
- [ ] Test boot_config commands on a single node
- [ ] Verify all packages install without errors
- [ ] Confirm inter-node connectivity (if multi-node)
- [ ] Test software stack end-to-end on one node

**Checkpoint:** A fresh node installs all software via boot_config and is ready.

### Walkthrough Questions
> 1. "Are there dependencies between software components?"
> 2. "Does the software need to build from source, or are packages available?"

---

## Phase 3: Experiment Implementation
**Goal:** The measurement/experiment logic works correctly.

- [ ] Implement data collection in `experiment.py`
- [ ] Add parameter handling for experiment variables
- [ ] Write data output in structured format (JSON/CSV)
- [ ] Implement error handling and retries
- [ ] Add `### PROGRESS:` markers for all major steps

**Checkpoint:** A single run produces valid, parseable output data.

### Walkthrough Questions
> 1. "What's the simplest version of the experiment that produces useful data?"
> 2. "Are there existing tools/scripts you want to integrate?"

---

## Phase 4: Pilot Run (Smoke Test)
**Goal:** End-to-end validation with minimal parameters.

- [ ] Run with smallest parameter set (1 value per variable, 1 repetition)
- [ ] Verify data collection produces valid output
- [ ] Check progress reporting works in WebUI
- [ ] Test Stop button triggers clean teardown
- [ ] Verify data appears in `data/` directory

**Checkpoint:** One complete cycle: deploy → measure → collect → analyze → teardown.

### Walkthrough Questions
> 1. "What minimal parameters would validate the full pipeline?"
> 2. "How long should the shortest useful run take?"

---

## Phase 5: Full Experiment
**Goal:** Execute the complete experiment with all parameters.

- [ ] Run full parameter space
- [ ] Monitor progress via Build Log or `notebooks/progress.ipynb`
- [ ] Handle any failures (retry, skip, adjust)
- [ ] Verify all expected data files are collected
- [ ] Check data completeness (no missing configurations)

**Checkpoint:** All planned configurations have valid results.

### Walkthrough Questions
> 1. "Do you need to run this in stages, or all at once?"
> 2. "What's your plan if you run out of time mid-experiment?"

---

## Phase 6: Analysis
**Goal:** Transform raw data into insights.

- [ ] Load all result data into analysis notebook
- [ ] Generate summary statistics per configuration
- [ ] Create visualizations (charts, tables, heatmaps)
- [ ] Compare against baselines or expectations
- [ ] Document findings and conclusions

**Checkpoint:** `notebooks/results.ipynb` has complete analysis with charts.

### Walkthrough Questions
> 1. "What visualization would best communicate your results?"
> 2. "Do you need statistical tests (t-test, ANOVA, etc.)?"

---

## Phase 7: Documentation & Sharing
**Goal:** Make the experiment reproducible and shareable.

- [ ] Update README with results summary
- [ ] Clean up directory (remove temp files, organize data)
- [ ] Fill in `description_long` in `weave.json`
- [ ] Publish to Artifact Manager (if sharing): `/publish-artifact`
- [ ] Archive raw data for long-term storage

**Checkpoint:** Another researcher could reproduce your experiment from the weave.

### Walkthrough Questions
> 1. "Do you plan to share this with others?"
> 2. "Is the raw data small enough to include, or should it be downloaded separately?"

---

## Future Enhancements

- [ ] [Items identified during the design walkthrough]
- [ ] Multi-site comparison
- [ ] Longer duration observations
- [ ] Additional metrics
