matlab-create-experiment

# Create Experiment for Experiment Manager

Plans and creates experiments in MATLAB Experiment Manager by analyzing user code or problem
descriptions, determining the experiment type, and generating the appropriate experiment
function, hyperparameter table, and experiment object.

## When to Use
- User has a MATLAB script/function and wants to sweep parameters or hyperparameters
- User asks to create an experiment or compare configurations
- User describes a problem and wants to explore parameter space
- User wants to track outputs across different parameter combinations

## When NOT to Use
- User is debugging an existing experiment or training failure
- User wants to run, resume, or view results of an existing experiment
- User already has a working Experiment Manager experiment set up
- User wants to edit experiment settings (hyperparameters, strategy, description) — direct them to make changes in the Experiment Manager app. However, editing the experiment function code (.m file) is allowed.
- User wants Bayesian optimization or random sampling strategy — direct them to configure from the Experiment Manager app

---

## Autonomy Model

This skill follows a guidance + autonomy pattern. Decision points are tagged:

| Tag | Meaning |
|-----|---------|
| `[user]` | Always pause and ask. Non-negotiable. |
| `[auto]` | Agent decides silently. Escalates on failure. |
| `[depends]` | Resolved by clarity of signals — auto if clear, ask if ambiguous. |

After analysis, tell the user how you intend to work in one plain sentence.
Always add: "Let me know if you'd prefer more or less control."

---

## Phase 1: Analysis

Read the user's code or problem description and classify the experiment type.

### Type Classification

Classify into one of three types using API-level and semantic signals.

**IMPORTANT:** If semantic signals indicate training (even without explicit DL API calls),
classify as training — NOT general purpose.

| Type | Signals | Template class |
|------|---------|----------------|
| General purpose | No DL functions, no training indicators. Optimization, simulation, data analysis. | `'experiments.internal.experimentTemplates.MATLABFunction'` |
| Built-in training | Uses `trainnet`/`trainNetwork`/`trainingOptions`, standard layers, datastores. OR: file name contains "train", user mentions "classification"/"transfer learning". | `'experiments.internal.experimentTemplates.BlankTrainnetTraining'` |
| Custom training (custom loop) | Uses `dlnetwork`/`dlfeval`/`dlgradient`/`dlarray`, manual gradients, GANs. OR: training loop with loss computation, user mentions "fine-tune"/"detector". | `'experiments.internal.experimentTemplates.CustomTraining'` |

### Classification Priority
1. Training loop structure (epoch iteration, loss tracking) → Custom training
2. Sets up data/layers/options without looping → Built-in training
3. Neither semantic nor API signals indicate training → General purpose

### Discovery Variables

| Variable | Tag | Notes |
|----------|-----|-------|
| Experiment type | `[depends]` | Auto if signals are clear; ask if ambiguous |
| Parameters to sweep | `[depends]` | Auto-infer from hardcoded values; ask if unclear |
| Parameter values | `[auto]` | Suggest 2-3 alternatives around hardcoded values |
| Init function needed | `[auto]` | Yes if expensive ops independent of params detected |
| Function signature | `[auto]` | Determined by type (see REFERENCES.md) |

Exit criteria: type classified, parameters identified, outputs known.

---

## Phase 2: Design

Generate the experiment function and prepare the full design for user review.

1. **Description** — Create a 2-4 line description covering: what the experiment does,
   parameters being swept, outputs captured per trial, and evaluation criterion.

2. **Parameters** — Build the parameter table (Name | Values | Description).
   - Hardcoded value → suggest 2-3 alternatives around it
   - Categorical → list reasonable alternatives
   - `[auto]` Warn if total trials > 50 (suggest reducing values)

3. **Function signature** — Select based on type:

   | Type | Signature |
   |------|-----------|
   | General purpose | `[out1, out2, ...] = func(params)` |
   | Built-in (Form A, targets in datastore) | `[trainingData, net, lossFcn, options] = func(params)` |
   | Built-in (Form B, targets separate) | `[trainingData, targets, net, lossFcn, options] = func(params)` |
   | Custom training | `output = func(params, monitor)` |

   Last 3 outputs for built-in must always be `net`, `lossFcn`, `options`.
   See references/REFERENCES.md for Form A vs B selection guide and supported loss functions.

4. **Generate experiment function** — Adapt user's code into the experiment function.

   **Heading convention when presenting:**
   - General purpose → "Generated Experiment Function"
   - Built-in training → "Generated Setup Function"
   - Custom training loop → "Generated Training Function"

   **Key rules:**
   - Use `params.<field>` for all tunable values (never hardcode swept values)
   - Each `params.<field>` is a single scalar value (numeric, string, or logical) — Experiment Manager assigns one value per trial. Never loop over parameter values inside the function; the sweep is handled externally.
   - Use `'Plots', 'none'` in trainingOptions
   - Include H1 help comment block
   - Use absolute paths for all file/data references — see REFERENCES.md § "Absolute Path Rules"
   - For custom training monitor pattern — see REFERENCES.md § "Custom Training Monitor Pattern"

   | Type | Body contains | Returns |
   |------|--------------|---------|
   | General purpose | User's computation logic, including figure/plot code | Named outputs (any serializable type) |
   | Built-in training | Data loading, network definition, trainingOptions | [data..., net, lossFcn, options] |
   | Custom training | Training loop with monitor integration, including figure/plot code | output (any serializable type) |

5. **`[auto]` Initialization function** — If