From 95f2fb72dbcfa65a9f234e0e27990964c9a84d73 Mon Sep 17 00:00:00 2001
From: mathias <mathias.bergqvist@gmail.com>
Date: Wed, 27 May 2026 22:00:02 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20add=20experiments/README.md=20=E2=80=94?=
 =?UTF-8?q?=20naming=20convention=20and=20run=20workflow?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 experiments/README.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)
 create mode 100644 experiments/README.md

diff --git a/experiments/README.md b/experiments/README.md
new file mode 100644
index 0000000..2076098
--- /dev/null
+++ b/experiments/README.md
@@ -0,0 +1,32 @@
+# Experiments
+
+One directory per experiment run. Large outputs (embeddings, checkpoints, logs) are gitignored. Only metric summaries are committed to `results/summaries/`.
+
+## Naming convention
+
+```
+YYYYMMDD-HHMMSS-phase-N-short-description/
+  config.yaml       parameters used for this run (committed via results/summaries/)
+  metrics.json      final metric snapshot (committed via results/summaries/)
+  embeddings/       (gitignored — large)
+  checkpoints/      (gitignored — large)
+  logs/             (gitignored — large)
+```
+
+## Git tag convention
+
+Every run that produces reportable metrics gets a tag:
+
+```
+exp/YYYYMMDD-phase-N-description
+```
+
+Example: `exp/20260601-phase-0-mae-baseline`
+
+## Starting a run
+
+```bash
+task experiment:run -- --spec specs/phase-0-ssl-feasibility.md --tag my-run-description
+```
+
+The runner creates the directory, writes config, runs the experiment, and outputs metrics.json.