# Experiment Specification: [TITLE]

> **How to use this template:** Run `/design-experiment` and Claude will walk you
> through filling in each section by asking targeted questions. You don't need to
> know anything about spec-driven development — the walkthrough guides you.

---

## 1. Research Overview

- **Research Question**: [What are you trying to answer or demonstrate?]
- **Hypothesis**: [What do you expect to find? What outcome would confirm/deny your hypothesis?]
- **Domain**: [networking / distributed systems / security / ML/HPC / edge computing / other]
- **Background**: [Brief context — why does this matter?]

### Walkthrough Questions
> 1. "What research question are you investigating? Even a rough idea is fine."
> 2. "What do you expect to find? (It's OK to say 'I don't know yet')"
> 3. Follow-up if vague: "Can you describe what a successful experiment looks like?"

---

## 2. Experiment Type

- **Category**: [measurement / comparison / stress-test / proof-of-concept / simulation]
- **Methodology**: [controlled experiment / A/B test / parameter sweep / time-series observation / exploratory]
- **Repetitions**: [How many times should each configuration run?]

### Walkthrough Questions
> 1. "What kind of experiment is this — are you measuring performance, comparing approaches, stress-testing limits, or proving a concept works?"
> 2. "Will you vary parameters (like packet size, number of nodes, algorithm) and measure the effect?"
> 3. Follow-up if sweep: "How many parameter values? Can different configurations run in parallel?"
> 4. Follow-up if comparison: "What are you comparing? Do you have a baseline?"

---

## 3. Infrastructure Requirements

### Nodes
| Role | Count | Cores | RAM (GB) | Disk (GB) | Image | Special Hardware |
|------|-------|-------|----------|-----------|-------|-----------------|
| [role] | [N] | [N] | [N] | [N] | [image] | [none/GPU/FPGA/SmartNIC] |

### Networking
- **Topology**: [star / mesh / ring / tree / point-to-point / none]
- **Network type**: [FABNetv4 / L2Bridge / L2STS / L2PTP / none]
- **Cross-site**: [yes/no — if yes, which sites or "auto"?]
- **External access needed**: [yes/no]
- **Bandwidth requirements**: [NIC_Basic sufficient? Dedicated NIC needed?]

### Software Stack
- **OS packages**: [list of apt packages]
- **Python packages**: [list of pip packages]
- **Containers**: [Docker images if any]
- **Custom software**: [repos to clone, builds to run]

### Walkthrough Questions
> 1. "How many nodes do you need, and do they have different roles (e.g., server/client, controller/worker)?"
> 2. "Do nodes need to communicate with each other? If so, what kind of network — isolated L2, routed IP, or internet-accessible?"
> 3. "Do nodes need to be at different FABRIC sites, or can they be co-located?"
> 4. "Do you need any special hardware — GPUs, FPGAs, SmartNICs, or fast NVMe storage?"
> 5. "What software needs to be installed? Any specific versions?"
> 6. Follow-up if GPU: "Which GPU model? How many per node? What CUDA/driver version?"
> 7. Follow-up if cross-site: "Do you need low-latency paths? Any site preferences?"
> 8. Follow-up if many nodes: "Can we start with a smaller test (2-3 nodes) and scale up?"

---

## 4. Experiment Parameters

- **Independent variables**: [what you change between runs]
- **Dependent variables**: [what you measure as output]
- **Control variables**: [what stays constant]

| Parameter | Values / Range | Unit |
|-----------|---------------|------|
| [param1]  | [values]      | [unit] |
| [param2]  | [values]      | [unit] |

- **Total configurations**: [N] (product of all parameter values)
- **Runs per configuration**: [N]
- **Total experiment runs**: [configurations x repetitions]

### Walkthrough Questions
> 1. "What will you change between runs (the independent variables)?"
> 2. "What will you measure as the result (the dependent variables)?"
> 3. "What range of values for each parameter?"
> 4. Follow-up: "How many repetitions per configuration for statistical confidence?"
> 5. Follow-up if large space: "Can we prioritize — which parameters matter most?"

---

## 5. Data Collection

- **Metrics**: [what to measure — throughput, latency, CPU usage, custom]
- **Collection method**: [tool output, log parsing, custom scripts, monitoring stack]
- **Collection frequency**: [per-test, periodic (every N seconds), continuous]
- **Data format**: [JSON / CSV / raw logs]
- **Storage location**: [data/ subdirectory structure]
- **Expected data volume**: [rough estimate — KB, MB, GB]

### Walkthrough Questions
> 1. "What metrics will you collect? (e.g., throughput, latency, CPU, memory, custom application metrics)"
> 2. "What tools produce the data? (e.g., iperf3, ping, your own script)"
> 3. "How often do you need to sample — once per test, every second, continuously?"
> 4. Follow-up: "What format should results be in — JSON for analysis, CSV for spreadsheets, or raw logs?"

---

## 6. Success Criteria

- **Minimum viable result**: [what constitutes a successful run]
- **Expected outcome**: [what you hope to see]
- **Statistical requirements**: [confidence level, min samples, significance test]
- **Comparison baselines**: [what to compare against — prior work, theoretical limits, etc.]

### Walkthrough Questions
> 1. "What does 'success' look like for this experiment?"
> 2. "Do you need statistical significance, or is a qualitative demonstration enough?"
> 3. Follow-up if stats: "What confidence level? How many samples do you need?"

---

## 7. Constraints & Risks

- **Time budget**: [hours/days available for the full experiment]
- **Resource limits**: [max nodes, max cores, FABRIC project quota]
- **Site preferences**: [specific sites needed or sites to avoid]
- **Lease duration**: [how long slices need to stay alive — hours/days]
- **Known risks**: [site capacity, software compatibility, token expiry]
- **Mitigation strategies**: [fallback sites, retry logic, checkpointing]

### Walkthrough Questions
> 1. "How much time do you have for this experiment?"
> 2. "Are there any resource limits you know about (project quota, specific sites required)?"
> 3. "How long does each run need to stay alive?"
> 4. Follow-up: "What should happen if a site is unavailable or a node fails?"

---

## 8. Execution Plan

- **Deployment mode**: [single slice / multi-slice sequential / multi-slice parallel]
- **Autonomy level**: [fully autonomous / semi-supervised / manual checkpoints]
- **Error recovery**: [retry N times / try different site / skip and continue / halt]
- **Checkpoint/resume**: [needed? save state every N runs?]
- **Output**: [where to find results when done]

### Walkthrough Questions
> 1. "Should this run fully autonomously, or do you want to approve each step?"
> 2. "If something fails mid-run, should it retry, skip, or stop?"
> 3. Follow-up if long: "Do you need checkpoint/resume support so you can stop and continue later?"
