Lab
The lab is where metric ideas are explored before promotion. This demo shows the bench rules only; the notebook, the experiment scripts, and the metric registry are private to the athlete's own installation.
Experiments
Throwaway analysis for a metric idea. Nothing here is imported by a package, tested, or wired into a report.
cp experiments/template.py experiments/<name>.py
uv run --env-file .env python experiments/<name>.py
Rules:
- One file per idea, self-contained and runnable.
- Print a table and save plots to
data/lab/(gitignored) viahobbyjogging_report.shell.table/save. - No tests, no
analysis/exports, no CLI commands โ an experiment must be deletable without touching anything else. - Use
./lab.shfor the interactive version of the same thing. - If it survives the gate in
docs/METRICS.md, promote it: pure function inanalysis/plus tests, cheapest renderer first, then charts, then dashboard. - If it does not, delete the file and leave a one-line "rejected" card so the idea is not re-litigated.
Lab session ground rules
- Scope. The lab explores; promotion is a package/root step. Writes stay
in
experiments/and lab docs; never package code, schema, or reports. - Read-only data. No imports, sync, maintenance, triage, or dashboard
regeneration. Anything risky runs against a copy in
/tmp/opencode/. - One idea, one question. The docstring states the hypothesis, formula, guards, the naive baseline it must beat, and what would falsify it. Definition changes after looking at results are recorded as iterations.
- Coverage first. Print n, date span, and exclusions before any conclusion.
- Canonical model. Use
DataSourceand existinganalysis/helpers; SQL is for feasibility checks, not the metric. - Stability. Before proposing promotion, split by year, illness, and sparse-data periods, and check outlier and guard sensitivity.
- Disposition. Every idea ends as promote handoff, park (tested and deferred; keep the file), block (never started; name the missing prerequisite), or reject (delete the file). No open-ended results.
- Cards. The lab drafts promoted/rejected card text; the root session
writes and commits the card in
docs/METRICS.md. - Commits. Finished experiments are committed here; never stage unrelated in-progress edits; do not push.
- Minimal. The smallest experiment that settles the question.
- Impact per unit of effort. Pick the highest-impact, lowest-workload idea next; the list order is not a schedule. An idea that unblocks or invalidates other measurements outranks a new one. Blocked items stay out of the queue until their prerequisite lands.