| name | cell-source-isolation |
| description | Use when writing or editing source files inside an `experiments/expNN_*/eNNx/` cell directory, or about to add a `_lib/` / `utils/` / `helpers/` directory under `experiments/` — enforces root-canonical filename rule (cell source files must mirror project-root filenames), forbids shared helper directories, and gates function reuse to two options: import unmodified from root, or copy the entire root file into the cell and edit the copy. |
Cell Source Isolation
Overview
A cell is a frozen snapshot of source files at the time of run. Once a cell has been run and its outputs / metrics committed, its source files are evidence, not editable — and duplication across cells is the point, because it guarantees each cell can be re-run independently without depending on shared state that some other cell may have quietly changed.
Violating the letter of the rules is violating the spirit of the rules.
When to Use
- Writing or editing source files inside a cell directory (
experiments/expNN_*/eNNx/)
- Writing the runner script for a new cell
- Deciding where a cache should live (cell-local vs shared at experiment level)
- Considering adding a shared helper directory (
_lib/, utils/, helpers/, common/) under experiments/
Terminology
- Root files: the canonical source files at the project root (e.g.
train.py, simulate.py, benchmark.py, pipeline.py, etc.) that
define the production / default pipeline.
- Runner script: whatever script actually launches the cell — e.g. a
SLURM
run.sbatch, a run.sh, a run.bat, a Makefile target, or a
docker-compose.yml. Use whatever is idiomatic for the project.
- Root-canonical filename: a source filename that exists at the project
root. Cell source files must mirror these names — a cell's
train.py is
a copy (possibly modified) of the project-root train.py, never a new
invented filename.
For the definitions of experiment (expNN_*/) and cell (eNNx/), and
for the rules about creating / numbering / not editing prior experiment
directories, see the sibling experiment-layout skill.
The Rules
1. Cell directories contain ONLY root-canonical filenames
The ONLY source files allowed in experiments/expNN_*/eNNx/:
| File | Purpose |
|---|
Copies of root files (e.g. train.py, simulate.py, pipeline.py, …) | Copied verbatim from the project root, then optionally modified for this variant. Only copy a root file if this cell needs to modify it. |
Runner script (e.g. run.sbatch, run.sh, Makefile) | Cell-specific job script that launches this cell. |
NOT allowed under any circumstance:
_lib/, lib/, helpers/, utils/, common/ — no shared-helper directoriesutils.py, helpers.py, model.py, data.py, *_helpers.py, extra_*.py — no new top-level source files- Any source filename that does not exist at the project root
Auto-generated artifacts that go in cell dirs are fine (and should be
gitignored). Typical examples include:
logs/, checkpoints/, outputs/, results/, _runtime/, .cache/
Use whatever names are idiomatic for the project — the rule is just that
source code must mirror root filenames; artifacts are unrestricted.
2. Function reuse — import or copy
Two and only two ways to use a root function in a cell:
| Need | Action |
|---|
| Use a root function unmodified | Import it from the root module (e.g. from pipeline import preprocess, from simulate import run_step). Root files are imported as-is. |
| Modify a root function for this variant | Copy the entire root file into the cell, edit the copy. The cell's local copy shadows the root for that cell. |
You never edit the root file from inside an experiment. Root is the
production pipeline; experiments cannot mutate it. New helpers needed by an
experiment go INSIDE the copied root file in the cell.
If multiple cells need the same new helper, each cell carries its own copy
of the modified root file. The duplication is the point — it guarantees
that re-running cell e04b a year from now does not depend on a _lib/
function that some other cell quietly changed.
3. Each cell has its own runner script
The runner script (whatever form it takes — sbatch, shell script, Makefile,
batch file, docker run invocation):
- Runs from the cell's directory (e.g.
cd …/experiments/expNN_*/eNNx or
the equivalent --chdir flag)
- Invokes the cell's local copies of source files where present, and root
files otherwise
- Writes outputs / logs into the cell's own artifact directories
4. Caches: cell-local or shared at experiment level
Allowed cache locations:
| Path | Scope |
|---|
eNNx/<artifact_dir>/ (logs, checkpoints, outputs, runtime, etc.) | One cell |
expNN_*/_shared_<name>_cache/ | All cells of this experiment that share the same input (dataset, simulation seed, fixture, etc.) |
Caches are auto-generated, not source. Add binary artifacts to .gitignore.
Source code never goes under _shared_*.
Quick Reference
What may live inside a cell directory:
experiments/expNN_*/eNNx/
├── train.py ← copy of root train.py (only if this cell modifies it)
├── simulate.py ← copy of root simulate.py (only if this cell modifies it)
├── run.sbatch ← runner script (sbatch / sh / Makefile / etc.)
├── logs/ ← auto-generated, gitignored
├── checkpoints/ ← auto-generated, gitignored
└── outputs/ ← auto-generated, gitignored
experiments/expNN_*/
└── _shared_<name>_cache/ ← optional, shared across cells of THIS experiment only
NOT allowed inside a cell directory:
eNNx/
├── <name>.py ✗ if <name>.py does NOT exist at the project root
├── extra_<name>.py ✗ invented filename, not root-canonical
├── <name>_v2.py ✗ ditto — modified copies keep the original name
├── lib/ ✗ no source-code subdirs, regardless of what's in root
├── helpers/ ✗ ditto
└── utils/ ✗ ditto (even if `utils/` exists at root — flatten into the copied root file)
The test for a source filename is: does this exact filename exist at the
project root (or src/)? If yes, it's allowed (as a verbatim or modified
copy). If no, it's forbidden — even if the name is conventional. So a
cell's utils.py is fine iff the project root has utils.py; otherwise
the helper goes inside the copied root file that needs it.
Artifact directories are unrestricted — name them whatever the project uses.
Decision Flow
Need a function from the root pipeline in this cell?
│
▼
Use it unmodified?
│
├── yes ──▶ Import it: `from <root_module> import <fn>`
│
└── no, need to modify it
│
▼
Copy the ENTIRE root file into the cell.
Edit the copy. The cell's local copy shadows
root for this cell.
│
▼
Other cells need the same change?
│
└── yes ──▶ Each cell carries its own copy.
Duplication is the point —
never extract into `_lib/`.
Common Mistakes & Rationalizations
| Excuse / mistake | Reality |
|---|
"I'll add a _lib/ for shared helpers across cells" | Forbidden. Helpers live inside the copied root file in each cell. The duplication ensures isolation. |
| "I'll edit the root pipeline file to add the new function this experiment needs" | Forbidden. Root is read-only from experiments. Copy the file into the cell and edit the copy. |
"I'll just put a utils.py in the cell, it's still inside the cell dir" | Forbidden. Source filenames inside a cell must match a root canonical file. |
Red Flags — STOP and Reset
If you find yourself about to do any of these, STOP, surface the situation to
the user, and propose a non-destructive alternative:
- Creating a source file in a cell whose name does not exist at the project root
- Creating a source-code subdirectory under a cell (artifact dirs like
logs/, outputs/, checkpoints/ are fine; lib/, utils/, helpers/ are not)
- Adding a new function to a root source file "to support an experiment"
Why These Rules Exist
The rules look pedantic. They exist because every weakening creates a path to
non-reproducible results.
_lib/ rule: A helper used by 5 cells, edited mid-experiment to fix
a bug for cell 5, silently changes the behavior of cells 1–4 if they're
ever re-run. Result: the metric you committed for cell 1 no longer matches
what re-running cell 1 produces.- Copy-don't-share rule: Multiple cells modifying the same shared file
produces merge conflicts during parallel ablation, race conditions when
cells run concurrently, and silent regressions.
The duplication and rigidity are the point. They convert "an experiment
broke and I don't know why" into "experiment N is fine, this new experiment
M+1 is the one with the issue."
See also
experiment-layout — where the cell directory comes from (numbering, prior-experiments-read-only)lab-journal-discipline — how to record the run after the cell finishes
