---

name: configure-experiments description: "Configure Lightning-Hydra-Template experiments with Hydra defaults, CLI overrides, debug presets, log paths, multiruns, and Optuna sweeps." disable-model-invocation: true metadata: disco-role: operating license: MIT

Configure Experiments

Use this sub-skill when the user needs to edit or debug the template's Hydra configuration rather than implement model/data code or run long training.

Triggers

Read this sub-skill for tasks about:

• configs/train.yaml, configs/eval.yaml, defaults ordering, config groups, or MissingConfigException.
• CLI overrides such as trainer.max_epochs=20, +trainer.precision=16, experiment=example, debug=fdr, or list-style tags=[...].
• Experiment YAML files, reproducible hyperparameter settings, or converting ad-hoc commands into configs/experiment/*.yaml.
• Hydra multiruns (-m), globbed experiments, repeated seeds, or hparams_search=mnist_optuna.
• Hydra output directories, ${paths.*} interpolation, PROJECT_ROOT, tags, config printing, and debug presets.

Quick workflow

1. Inspect the config groups and composed config without training:

   python <this-skill>/sub-skills/configure-experiments/scripts/render_config_summary.py --repo-root . --config-name train.yaml --list-groups
   python <this-skill>/sub-skills/configure-experiments/scripts/render_config_summary.py --repo-root . --config-name train.yaml --override experiment=example --resolve
   

2. Decide whether the change belongs in:
   • a group file under configs/data, configs/model, configs/trainer, configs/callbacks, or configs/logger;
   • a top-level defaults edit in configs/train.yaml or configs/eval.yaml;
   • a reproducible experiment file under configs/experiment;
   • a one-off CLI override.
3. For debugging, prefer debug=fdr for one train/val/test step, debug=limit for reduced batches, debug=overfit for overfit-to-batches checks, and debug=profiler for timing.
4. Before using sweeps, ensure optimized_metric matches a metric logged by the model. The default Optuna config expects val/acc_best.
5. If config targets fail to import, route to customize-data-model and run its _target_ checker.

Read references

• Hydra configuration: defaults list, config groups, override syntax, paths, tags, and composed config checks.
• Sweeps and debugging: multiruns, Optuna, repeated seeds, debug presets, and safe sweep cautions.
• Troubleshooting: config group misses, interpolation failures, tag prompts, metric mismatch, and stale target strings.

Bundled script

• scripts/render_config_summary.py: compose a train/eval config from a target checkout, list groups, print selected fields, and optionally resolve interpolations. It does not run training or data downloads.

Boundaries

• For train_command, checkpoint resume/eval, callbacks/loggers as runtime behavior, or accelerator execution, use train-evaluate.
• For adding DataModules, LightningModules, components, optimizers, schedulers, or package renames, use customize-data-model.
• For pytest/CI smoke selection or package metadata maintenance, use test-maintain-template.