--- name: organize-ml-workspace description: > Decide where files live in an ML experimentation project: reusable code in `src/<pkg>/`, one `# %%` script per experiment in `experiments/`, design notes + index in `journal/`, reports in `reports/`, agent-only probes in `scratch/`. Owns the layout, the file-creation rules (one file per experiment, ask before editing), and the jupytext `# %%` script convention. Never imposes `data/` — the user owns that.

TRIGGER — any of: - Starting a new ML project / scaffolding a workspace. - About to create the first experiment file in a project. - About to create `src/<pkg>/data.py` / `features.py` / `pipeline.py` / `evaluate.py` for the first time. - About to write a `.ipynb` for experimentation — redirect to a `# %%` script under `experiments/`. - User asks where something should live, how to organize the project, or how to set up the workspace. - About to add a new experiment iteration — decide new file vs edit existing (ask the user).

SKIP when: the file is clearly part of an already-populated module (e.g., adding a function to existing `features.py`); pure refactor inside a single existing file; pipeline declaration mechanics (`build-ml-pipeline`); evaluation mechanics (`evaluate-ml-pipeline`); skore symbol lookup (`python-api`).

HOW TO USE: **first run the Detection table** below — if any signal matches, glue to existing conventions (do not rename or move folders). If no signal matches, scaffold the default layout. **Emit the Pre-flight checklist as visible text and read the Stop conditions before any file is created or edited.** Use templates in `templates/`; copy and adapt, do not rewrite from scratch. ---

# Organize ML Workspace

Where things live, when to create a new file, what each file is allowed to contain.

## Next-step pointers — where you go after this skill

| You came here for… | → next | |---|---| | Bootstrap a fresh workspace | → `python-env-manager` § Bootstrap; then `iterate-ml-experiment` § 0 | | First experiment script | → `iterate-ml-experiment` § 0 for the design note | | Add a new experiment iteration | → `iterate-ml-experiment` § 1 (new vs edit decision) | | Pipeline / evaluate / smoke-test content | → `build-ml-pipeline` / `evaluate-ml-pipeline` / `smoke-test-ml-pipeline` |

Always re-emit the Pre-flight checklist with evidence before declaring the turn done.

## Sibling skills — open just-in-time

Don't pre-read every sibling at session start (paralysis). Open each sibling SKILL.md when a step calls for it (e.g. open `python-env-manager` before G-ENV-MGR; open `iterate-ml-experiment` before handing off the design-note write). Emit this tracker once per turn:

``` Sibling skills (just-in-time): - data-science-python-stack, python-env-manager, python-api, python-code-style, iterate-ml-experiment, explore-ml-data, build-ml-pipeline, evaluate-ml-pipeline, test-ml-pipeline, smoke-test-ml-pipeline ```

## Stop conditions — read before anything else

- **Missing dependency.** If `import skore` raises, STOP. Invoke `python-env-manager` for the install command. Do not drop `skore.Project` in favor of `mlflow` / pickles / "print metrics" — the workspace contract assumes a Project on disk. - **Symbol from memory is forbidden.** Any `skore.Project` / `project.put` / `skore.evaluate` signature must come from a `python-api` call this turn. - **Existing layout wins — detect first.** Run the Detection table before scaffolding. Don't rename, relocate, or "tidy up" existing folders. - **Notebooks are not silent.** Existing `.ipynb` files in the experiment folder → surface the convention shift and ask. Don't auto-convert. - **Scratch is read-only against the skore Project.** Probes under `scratch/<ts>_<short>.py` may call `project.get(...)`, `project.summarize()`, walk an existing report. They MUST NOT call `skore.evaluate(...)` or `project.put(...)`. When `project.get(key)` raises `KeyError`, the fix is the lookup shape: `get` is by **id**, not by `key`. Use `summarize()` → `(key, id)` → `get(id)`. Never substitute by re-running `evaluate` + `put`. - **Tabular library is asked, not assumed (G-TABULAR).** Pandas being importable via skore is not a pick. Invoke `data-science-python-stack` for the structured ask. Free-text ("quick", "you pick") does NOT resolve. Persisted in JOURNAL.md Status `Workspace decisions`. - **Package name is asked, not inferred (G-PKG-NAME).** Before any `pyproject.toml` / manifest creation (including `pixi init` / `uv init` / `poetry init`), fire an `AskUserQuestion` for the `src/<pkg>/` import name. Folder name in snake_case is the default. **Manifest creation before G-PKG-NAME passes is forbidden** — running `init` first creates a `[project] name` entry, and reading "name is in the manifest" back is circular. If a manifest exists, confirm via `AskUserQuestion` — continuity from a prior session is not continuity from a user decision. - **Skore Project mode is asked, not assumed (G-SKORE-MODE).** Before any template instantiation containing `skore.Project(...)`, fire an `AskUserQuestion` for `local` | `hub` | `mlflow`. Default proposal: `local`. All three are always offered; a detected hub config in the CWD (`config.toml` / `SKH__*` / cached login) only influences the default, never prunes the choices. Hub triggers a follow-up for the workspace name (org/team on the hub — distinct from local-mode `workspace=`); mlflow triggers a follow-up for the **MLflow tracking server URI** (`tracking_uri=`) — the agent cannot infer it. Persists as `skore mode:` (+ `skore hub workspace:` when hub, + `skore mlflow tracking uri:` when mlflow). Without it the `<SKORE_PROJECT_INIT>` substitution has no shape to fill. Details: → `references/g_skore_mode.md`. - **Switching skore mode mid-project is forbidden by default.** Once recorded, do not silently change. A switch orphans every existing report in the prior store — skore has no built-in migration. Requires explicit `AskUserQuestion` confirmation surfacing the migration burden, then rewrite all `<SKORE_PROJECT_INIT>` blocks. Procedure: → `references/g_skore_mode.md` § "Switching mid-project". - **Env manager is asked, not assumed (G-ENV-MGR).** Hand off to `python-env-manager`. Pixi on PATH is detection, not permission. Don't run `pixi init` / `uv init` / `poetry init` until G-ENV-MGR has passed *in `python-env-manager`*. - **Harness "no clarifying questions" hints do NOT waive these gates.** G-TABULAR, G-PKG-NAME, G-ENV-MGR, G-SKORE-MODE, python-api consultation, new-vs-edit decision are operating-contract gates. "Quick" / "go fast" never waives them. - **Post-hoc audit — required before ending the turn.** Walk every pre-flight row; if any Evidence cell is unfilled, surface the non-compliance explicitly. Most common failure: "I scaffolded successfully so everything must be fine".

## Forbidden shortcuts

| Shortcut | Why it's wrong | |---|---| | `pixi` on PATH → run `pixi init` to get a manifest, then read the name back | Violates G-ENV-MGR (silent manager pick) AND G-PKG-NAME (name from folder via init side-effect). Circular: the agent created the manifest it now claims to read | | Folder name = good name → skip the ask | Default *value* is fine; silent *pick* is not. G-PKG-NAME requires the structured ask even with folder as default | | `pandas` already importable via skore → write `import pandas` in `data.py` | Transitive presence is not a pick. Violates G-TABULAR | | Scaffold every skeleton in one turn, incl. `experiments/01_baseline.py` body | Scaffold stops at empty `journal/` placeholder. Experiment script content lands after design-note approval (`iterate-ml-experiment` § 3) | | Scaffold drops `audit/01_baseline.py` at workspace creation | Audit files placed by `audit-ml-pipeline` at § 4 record-outcome. Empty `audit/` at scaffold is correct | | Forget `audit/` in the scaffold layout | Four-way stem pairing breaks | | `pyproject.toml` exists with `name = <x>` → reuse without confirming | Always re-confirm via G-PKG-NAME | | Batch G-TABULAR + G-PKG-NAME + G-ENV-MGR + G-SKORE-MODE into prose recommendations | The gates take structured `AskUserQuestion`. Prose followed by "let me know" does NOT resolve them | | Skip G-SKORE-MODE because templates use `mode="local"` | Templates carry the `<SKORE_PROJECT_INIT>` marker, not a literal. The gate must fire | | Pick `mode="hub"` without checking the workspace exists / user has access | Project init fails at first `put()` with an authorization error. Confirm during G-SKORE-MODE, not at execution time | | Pick `mode="mlflow"` and invent / default the `tracking_uri=` | The tracking URI is server-specific; the agent cannot infer it. Ask the user at the G-SKORE-MODE follow-up. No silent `http://localhost:5000` | | Folder has skore-hub config (`config.toml` / `SKH__*` / cached login) → present only `hub` (or `hub`+`local`), drop `mlflow` | Detected config is detection, not permission (cf. "Pixi on PATH"). The gate must always offer all three; config only sets the default highlight | | Substitute `pip install "skore[hub]"` / `"skore[mlflow]"` based on agent guess | Install variant comes from G-SKORE-MODE's recorded answer. `python-env-manager` reads that row, not agent intuition | | Silently change `skore mode:` mid-project to "fix" a broken init | Switching orphans existing reports. Always explicit `AskUserQuestion` first | | Hub substitution but leaving a directory-style `workspace=str(PROJECT_ROOT / "reports")` | In hub mode `workspace=` carries the **Hub workspace name** (e.g. `workspace="acme-corp"`), not an on-disk dir. mlflow rejects `workspace=` and uses `tracking_uri=`. Substitute the whole block, not just the mode literal | | mlflow substitution that keeps a `login(mode=...)` call | mlflow mode needs no skore login — auth is the MLflow server's concern. `login` belongs only to hub mode | | Local `workspace="reports"` (relative) instead of `str(PROJECT_ROOT / "reports")` (absolute) | Relative resolves against CWD; runs from other dirs write the store somewhere unexpected. Always absolute via `PROJECT_ROOT` | | Putting `skore.login(mode="hub")` after `skore.Project(...)` | `Project(...)` requires authenticated session in hub mode. `login` first | | Substituting `<SKORE_PROJECT_INIT>` in `audit/<stem>.py` independently of `experiments/<stem>.py` | Audit must open the same Project. Byte-identical copy from the experiment file is the rule | | Hub workspace name contains `/` (e.g. `acme/datasci`) | `workspace=` is a single Hub workspace identifier, not a path or a `<workspace>/<project>` join; a `/` is invalid. Reject at G-SKORE-MODE follow-up | | `project.get(key)` raised `KeyError` → re-run `evaluate` + `put` to "recover" | Lookup shape wrong (`get` is by id). Use `summarize()` → `get(id)` |

## Pre-flight — emit before any code

Each ticked box needs an Evidence line (format spec in `iterate-ml-experiment` § "Pre-flight evidence requirements"; see also `python-env-manager/references/preflight_evidence.md`).

``` Pre-flight (organize-ml-workspace): - [ ] `Workspace decisions` in `journal/JOURNAL.md` Status checked for pre-recorded gates (tabular, env_manager, package, skore mode) Evidence: lists each <gate>: <value | not recorded> | "n/a — JOURNAL.md does not exist yet (truly fresh)" - [ ] Tier 1 mandatory libs importable: sklearn, skrub, skore Evidence: Write scratch/<ts>_check_tier1.py + `pixi run python …` output. **Inline `python -c` is NOT evidence**. - [ ] Layout detection done: <existing | fresh> Evidence: ls/Glob on project root + matched signal from Detection - [ ] G-TABULAR resolved: pandas | polars Evidence: AskUserQuestion id=<id> via data-science-python-stack | JOURNAL.md Status (Workspace decisions) | user quote turn N - [ ] G-ENV

--- name: organize-ml-workspace description: > Decide where files live in an ML experimentation project: reusable code in `src/<pkg>/`, one `# %%` script per experiment in `experiments/`, design notes + index in `journal/`, reports in `reports/`, agent-only probes in `scratch/`. Owns the layout, the file-creation rules (one file per experiment, ask before editing), and the jupytext `# %%` script convention. Never imposes `data/` — the user owns that.

TRIGGER — any of: - Starting a new ML project / scaffolding a workspace. - About to create the first experiment file in a project. - About to create `src/<pkg>/data.py` / `features.py` / `pipeline.py` / `evaluate.py` for the first time. - About to write a `.ipynb` for experimentation — redirect to a `# %%` script under `experiments/`. - User asks where something should live, how to organize the project, or how to set up the workspace. - About to add a new experiment iteration — decide new file vs edit existing (ask the user).

SKIP when: the file is clearly part of an already-populated module (e.g., adding a function to existing `features.py`); pure refactor inside a single existing file; pipeline declaration mechanics (`build-ml-pipeline`); evaluation mechanics (`evaluate-ml-pipeline`); skore symbol lookup (`python-api`).

HOW TO USE: **first run the Detection table** below — if any signal matches, glue to existing conventions (do not rename or move folders). If no signal matches, scaffold the default layout. **Emit the Pre-flight checklist as visible text and read the Stop conditions before any file is created or edited.** Use templates in `templates/`; copy and adapt, do not rewrite from scratch. ---

# Organize ML Workspace

Where things live, when to create a new file, what each file is allowed to contain.

## Next-step pointers — where you go after this skill

| You came here for… | → next | |---|---| | Bootstrap a fresh workspace | → `python-env-manager` § Bootstrap; then `iterate-ml-experiment` § 0 | | First experiment script | → `iterate-ml-experiment` § 0 for the design note | | Add a new experiment iteration | → `iterate-ml-experiment` § 1 (new vs edit decision) | | Pipeline / evaluate / smoke-test content | → `build-ml-pipeline` / `evaluate-ml-pipeline` / `smoke-test-ml-pipeline` |

Always re-emit the Pre-flight checklist with evidence before declaring the turn done.

## Sibling skills — open just-in-time

Don't pre-read every sibling at session start (paralysis). Open each sibling SKILL.md when a step calls for it (e.g. open `python-env-manager` before G-ENV-MGR; open `iterate-ml-experiment` before handing off the design-note write). Emit this tracker once per turn:

``` Sibling skills (just-in-time): - data-science-python-stack, python-env-manager, python-api, python-code-style, iterate-ml-experiment, explore-ml-data, build-ml-pipeline, evaluate-ml-pipeline, test-ml-pipeline, smoke-test-ml-pipeline ```

## Stop conditions — read before anything else

- **Missing dependency.** If `import skore` raises, STOP. Invoke `python-env-manager` for the install command. Do not drop `skore.Project` in favor of `mlflow` / pickles / "print metrics" — the workspace contract assumes a Project on disk. - **Symbol from memory is forbidden.** Any `skore.Project` / `project.put` / `skore.evaluate` signature must come from a `python-api` call this turn. - **Existing layout wins — detect first.** Run the Detection table before scaffolding. Don't rename, relocate, or "tidy up" existing folders. - **Notebooks are not silent.** Existing `.ipynb` files in the experiment folder → surface the convention shift and ask. Don't auto-convert. - **Scratch is read-only against the skore Project.** Probes under `scratch/<ts>_<short>.py` may call `project.get(...)`, `project.summarize()`, walk an existing report. They MUST NOT call `skore.evaluate(...)` or `project.put(...)`. When `project.get(key)` raises `KeyError`, the fix is the lookup shape: `get` is by **id**, not by `key`. Use `summarize()` → `(key, id)` → `get(id)`. Never substitute by re-running `evaluate` + `put`. - **Tabular library is asked, not assumed (G-TABULAR).** Pandas being importable via skore is not a pick. Invoke `data-science-python-stack` for the structured ask. Free-text ("quick", "you pick") does NOT resolve. Persisted in JOURNAL.md Status `Workspace decisions`. - **Package name is asked, not inferred (G-PKG-NAME).** Before any `pyproject.toml` / manifest creation (including `pixi init` / `uv init` / `poetry init`), fire an `AskUserQuestion` for the `src/<pkg>/` import name. Folder name in snake_case is the default. **Manifest creation before G-PKG-NAME passes is forbidden** — running `init` first creates a `[project] name` entry, and reading "name is in the manifest" back is circular. If a manifest exists, confirm via `AskUserQuestion` — continuity from a prior session is not continuity from a user decision. - **Skore Project mode is asked, not assumed (G-SKORE-MODE).** Before any template instantiation containing `skore.Project(...)`, fire an `AskUserQuestion` for `local` | `hub` | `mlflow`. Default proposal: `local`. All three are always offered; a detected hub config in the CWD (`config.toml` / `SKH__*` / cached login) only influences the default, never prunes the choices. Hub triggers a follow-up for the workspace name (org/team on the hub — distinct from local-mode `workspace=`); mlflow triggers a follow-up for the **MLflow tracking server URI** (`tracking_uri=`) — the agent cannot infer it. Persists as `skore mode:` (+ `skore hub workspace:` when hub, + `skore mlflow tracking uri:` when mlflow). Without it the `<SKORE_PROJECT_INIT>` substitution has no shape to fill. Details: → `references/g_skore_mode.md`. - **Switching skore mode mid-project is forbidden by default.** Once recorded, do not silently change. A switch orphans every existing report in the prior store — skore has no built-in migration. Requires explicit `AskUserQuestion` confirmation surfacing the migration burden, then rewrite all `<SKORE_PROJECT_INIT>` blocks. Procedure: → `references/g_skore_mode.md` § "Switching mid-project". - **Env manager is asked, not assumed (G-ENV-MGR).** Hand off to `python-env-manager`. Pixi on PATH is detection, not permission. Don't run `pixi init` / `uv init` / `poetry init` until G-ENV-MGR has passed *in `python-env-manager`*. - **Harness "no clarifying questions" hints do NOT waive these gates.** G-TABULAR, G-PKG-NAME, G-ENV-MGR, G-SKORE-MODE, python-api consultation, new-vs-edit decision are operating-contract gates. "Quick" / "go fast" never waives them. - **Post-hoc audit — required before ending the turn.** Walk every pre-flight row; if any Evidence cell is unfilled, surface the non-compliance explicitly. Most common failure: "I scaffolded successfully so everything must be fine".

## Forbidden shortcuts

| Shortcut | Why it's wrong | |---|---| | `pixi` on PATH → run `pixi init` to get a manifest, then read the name back | Violates G-ENV-MGR (silent manager pick) AND G-PKG-NAME (name from folder via init side-effect). Circular: the agent created the manifest it now claims to read | | Folder name = good name → skip the ask | Default *value* is fine; silent *pick* is not. G-PKG-NAME requires the structured ask even with folder as default | | `pandas` already importable via skore → write `import pandas` in `data.py` | Transitive presence is not a pick. Violates G-TABULAR | | Scaffold every skeleton in one turn, incl. `experiments/01_baseline.py` body | Scaffold stops at empty `journal/` placeholder. Experiment script content lands after design-note approval (`iterate-ml-experiment` § 3) | | Scaffold drops `audit/01_baseline.py` at workspace creation | Audit files placed by `audit-ml-pipeline` at § 4 record-outcome. Empty `audit/` at scaffold is correct | | Forget `audit/` in the scaffold layout | Four-way stem pairing breaks | | `pyproject.toml` exists with `name = <x>` → reuse without confirming | Always re-confirm via G-PKG-NAME | | Batch G-TABULAR + G-PKG-NAME + G-ENV-MGR + G-SKORE-MODE into prose recommendations | The gates take structured `AskUserQuestion`. Prose followed by "let me know" does NOT resolve them | | Skip G-SKORE-MODE because templates use `mode="local"` | Templates carry the `<SKORE_PROJECT_INIT>` marker, not a literal. The gate must fire | | Pick `mode="hub"` without checking the workspace exists / user has access | Project init fails at first `put()` with an authorization error. Confirm during G-SKORE-MODE, not at execution time | | Pick `mode="mlflow"` and invent / default the `tracking_uri=` | The tracking URI is server-specific; the agent cannot infer it. Ask the user at the G-SKORE-MODE follow-up. No silent `http://localhost:5000` | | Folder has skore-hub config (`config.toml` / `SKH__*` / cached login) → present only `hub` (or `hub`+`local`), drop `mlflow` | Detected config is detection, not permission (cf. "Pixi on PATH"). The gate must always offer all three; config only sets the default highlight | | Substitute `pip install "skore[hub]"` / `"skore[mlflow]"` based on agent guess | Install variant comes from G-SKORE-MODE's recorded answer. `python-env-manager` reads that row, not agent intuition | | Silently change `skore mode:` mid-project to "fix" a broken init | Switching orphans existing reports. Always explicit `AskUserQuestion` first | | Hub substitution but leaving a directory-style `workspace=str(PROJECT_ROOT / "reports")` | In hub mode `workspace=` carries the **Hub workspace name** (e.g. `workspace="acme-corp"`), not an on-disk dir. mlflow rejects `workspace=` and uses `tracking_uri=`. Substitute the whole block, not just the mode literal | | mlflow substitution that keeps a `login(mode=...)` call | mlflow mode needs no skore login — auth is the MLflow server's concern. `login` belongs only to hub mode | | Local `workspace="reports"` (relative) instead of `str(PROJECT_ROOT / "reports")` (absolute) | Relative resolves against CWD; runs from other dirs write the store somewhere unexpected. Always absolute via `PROJECT_ROOT` | | Putting `skore.login(mode="hub")` after `skore.Project(...)` | `Project(...)` requires authenticated session in hub mode. `login` first | | Substituting `<SKORE_PROJECT_INIT>` in `audit/<stem>.py` independently of `experiments/<stem>.py` | Audit must open the same Project. Byte-identical copy from the experiment file is the rule | | Hub workspace name contains `/` (e.g. `acme/datasci`) | `workspace=` is a single Hub workspace identifier, not a path or a `<workspace>/<project>` join; a `/` is invalid. Reject at G-SKORE-MODE follow-up | | `project.get(key)` raised `KeyError` → re-run `evaluate` + `put` to "recover" | Lookup shape wrong (`get` is by id). Use `summarize()` → `get(id)` |

## Pre-flight — emit before any code

Each ticked box needs an Evidence line (format spec in `iterate-ml-experiment` § "Pre-flight evidence requirements"; see also `python-env-manager/references/preflight_evidence.md`).

``` Pre-flight (organize-ml-workspace): - [ ] `Workspace decisions` in `journal/JOURNAL.md` Status checked for pre-recorded gates (tabular, env_manager, package, skore mode) Evidence: lists each <gate>: <value | not recorded> | "n/a — JOURNAL.md does not exist yet (truly fresh)" - [ ] Tier 1 mandatory libs importable: sklearn, skrub, skore Evidence: Write scratch/<ts>_check_tier1.py + `pixi run python …` output. **Inline `python -c` is NOT evidence**. - [ ] Layout detection done: <existing | fresh> Evidence: ls/Glob on project root + matched signal from Detection - [ ] G-TABULAR resolved: pandas | polars Evidence: AskUserQuestion id=<id> via data-science-python-stack | JOURNAL.md Status (Workspace decisions) | user quote turn N - [ ] G-ENV

--- name: organize-ml-workspace description: > Decide where files live in an ML experimentation project: reusable code in `src/<pkg>/`, one `# %%` script per experiment in `experiments/`, design notes + index in `journal/`, reports in `reports/`, agent-only probes in `scratch/`. Owns the layout, the file-creation rules (one file per experiment, ask before editing), and the jupytext `# %%` script convention. Never imposes `data/` — the user owns that.

TRIGGER — any of: - Starting a new ML project / scaffolding a workspace. - About to create the first experiment file in a project. - About to create `src/<pkg>/data.py` / `features.py` / `pipeline.py` / `evaluate.py` for the first time. - About to write a `.ipynb` for experimentation — redirect to a `# %%` script under `experiments/`. - User asks where something should live, how to organize the project, or how to set up the workspace. - About to add a new experiment iteration — decide new file vs edit existing (ask the user).

SKIP when: the file is clearly part of an already-populated module (e.g., adding a function to existing `features.py`); pure refactor inside a single existing file; pipeline declaration mechanics (`build-ml-pipeline`); evaluation mechanics (`evaluate-ml-pipeline`); skore symbol lookup (`python-api`).

HOW TO USE: **first run the Detection table** below — if any signal matches, glue to existing conventions (do not rename or move folders). If no signal matches, scaffold the default layout. **Emit the Pre-flight checklist as visible text and read the Stop conditions before any file is created or edited.** Use templates in `templates/`; copy and adapt, do not rewrite from scratch. ---

# Organize ML Workspace

Where things live, when to create a new file, what each file is allowed to contain.

## Next-step pointers — where you go after this skill

| You came here for… | → next | |---|---| | Bootstrap a fresh workspace | → `python-env-manager` § Bootstrap; then `iterate-ml-experiment` § 0 | | First experiment script | → `iterate-ml-experiment` § 0 for the design note | | Add a new experiment iteration | → `iterate-ml-experiment` § 1 (new vs edit decision) | | Pipeline / evaluate / smoke-test content | → `build-ml-pipeline` / `evaluate-ml-pipeline` / `smoke-test-ml-pipeline` |

Always re-emit the Pre-flight checklist with evidence before declaring the turn done.

## Sibling skills — open just-in-time

Don't pre-read every sibling at session start (paralysis). Open each sibling SKILL.md when a step calls for it (e.g. open `python-env-manager` before G-ENV-MGR; open `iterate-ml-experiment` before handing off the design-note write). Emit this tracker once per turn:

``` Sibling skills (just-in-time): - data-science-python-stack, python-env-manager, python-api, python-code-style, iterate-ml-experiment, explore-ml-data, build-ml-pipeline, evaluate-ml-pipeline, test-ml-pipeline, smoke-test-ml-pipeline ```

## Stop conditions — read before anything else

- **Missing dependency.** If `import skore` raises, STOP. Invoke `python-env-manager` for the install command. Do not drop `skore.Project` in favor of `mlflow` / pickles / "print metrics" — the workspace contract assumes a Project on disk. - **Symbol from memory is forbidden.** Any `skore.Project` / `project.put` / `skore.evaluate` signature must come from a `python-api` call this turn. - **Existing layout wins — detect first.** Run the Detection table before scaffolding. Don't rename, relocate, or "tidy up" existing folders. - **Notebooks are not silent.** Existing `.ipynb` files in the experiment folder → surface the convention shift and ask. Don't auto-convert. - **Scratch is read-only against the skore Project.** Probes under `scratch/<ts>_<short>.py` may call `project.get(...)`, `project.summarize()`, walk an existing report. They MUST NOT call `skore.evaluate(...)` or `project.put(...)`. When `project.get(key)` raises `KeyError`, the fix is the lookup shape: `get` is by **id**, not by `key`. Use `summarize()` → `(key, id)` → `get(id)`. Never substitute by re-running `evaluate` + `put`. - **Tabular library is asked, not assumed (G-TABULAR).** Pandas being importable via skore is not a pick. Invoke `data-science-python-stack` for the structured ask. Free-text ("quick", "you pick") does NOT resolve. Persisted in JOURNAL.md Status `Workspace decisions`. - **Package name is asked, not inferred (G-PKG-NAME).** Before any `pyproject.toml` / manifest creation (including `pixi init` / `uv init` / `poetry init`), fire an `AskUserQuestion` for the `src/<pkg>/` import name. Folder name in snake_case is the default. **Manifest creation before G-PKG-NAME passes is forbidden** — running `init` first creates a `[project] name` entry, and reading "name is in the manifest" back is circular. If a manifest exists, confirm via `AskUserQuestion` — continuity from a prior session is not continuity from a user decision. - **Skore Project mode is asked, not assumed (G-SKORE-MODE).** Before any template instantiation containing `skore.Project(...)`, fire an `AskUserQuestion` for `local` | `hub` | `mlflow`. Default proposal: `local`. All three are always offered; a detected hub config in the CWD (`config.toml` / `SKH__*` / cached login) only influences the default, never prunes the choices. Hub triggers a follow-up for the workspace name (org/team on the hub — distinct from local-mode `workspace=`); mlflow triggers a follow-up for the **MLflow tracking server URI** (`tracking_uri=`) — the agent cannot infer it. Persists as `skore mode:` (+ `skore hub workspace:` when hub, + `skore mlflow tracking uri:` when mlflow). Without it the `<SKORE_PROJECT_INIT>` substitution has no shape to fill. Details: → `references/g_skore_mode.md`. - **Switching skore mode mid-project is forbidden by default.** Once recorded, do not silently change. A switch orphans every existing report in the prior store — skore has no built-in migration. Requires explicit `AskUserQuestion` confirmation surfacing the migration burden, then rewrite all `<SKORE_PROJECT_INIT>` blocks. Procedure: → `references/g_skore_mode.md` § "Switching mid-project". - **Env manager is asked, not assumed (G-ENV-MGR).** Hand off to `python-env-manager`. Pixi on PATH is detection, not permission. Don't run `pixi init` / `uv init` / `poetry init` until G-ENV-MGR has passed *in `python-env-manager`*. - **Harness "no clarifying questions" hints do NOT waive these gates.** G-TABULAR, G-PKG-NAME, G-ENV-MGR, G-SKORE-MODE, python-api consultation, new-vs-edit decision are operating-contract gates. "Quick" / "go fast" never waives them. - **Post-hoc audit — required before ending the turn.** Walk every pre-flight row; if any Evidence cell is unfilled, surface the non-compliance explicitly. Most common failure: "I scaffolded successfully so everything must be fine".

## Forbidden shortcuts

| Shortcut | Why it's wrong | |---|---| | `pixi` on PATH → run `pixi init` to get a manifest, then read the name back | Violates G-ENV-MGR (silent manager pick) AND G-PKG-NAME (name from folder via init side-effect). Circular: the agent created the manifest it now claims to read | | Folder name = good name → skip the ask | Default *value* is fine; silent *pick* is not. G-PKG-NAME requires the structured ask even with folder as default | | `pandas` already importable via skore → write `import pandas` in `data.py` | Transitive presence is not a pick. Violates G-TABULAR | | Scaffold every skeleton in one turn, incl. `experiments/01_baseline.py` body | Scaffold stops at empty `journal/` placeholder. Experiment script content lands after design-note approval (`iterate-ml-experiment` § 3) | | Scaffold drops `audit/01_baseline.py` at workspace creation | Audit files placed by `audit-ml-pipeline` at § 4 record-outcome. Empty `audit/` at scaffold is correct | | Forget `audit/` in the scaffold layout | Four-way stem pairing breaks | | `pyproject.toml` exists with `name = <x>` → reuse without confirming | Always re-confirm via G-PKG-NAME | | Batch G-TABULAR + G-PKG-NAME + G-ENV-MGR + G-SKORE-MODE into prose recommendations | The gates take structured `AskUserQuestion`. Prose followed by "let me know" does NOT resolve them | | Skip G-SKORE-MODE because templates use `mode="local"` | Templates carry the `<SKORE_PROJECT_INIT>` marker, not a literal. The gate must fire | | Pick `mode="hub"` without checking the workspace exists / user has access | Project init fails at first `put()` with an authorization error. Confirm during G-SKORE-MODE, not at execution time | | Pick `mode="mlflow"` and invent / default the `tracking_uri=` | The tracking URI is server-specific; the agent cannot infer it. Ask the user at the G-SKORE-MODE follow-up. No silent `http://localhost:5000` | | Folder has skore-hub config (`config.toml` / `SKH__*` / cached login) → present only `hub` (or `hub`+`local`), drop `mlflow` | Detected config is detection, not permission (cf. "Pixi on PATH"). The gate must always offer all three; config only sets the default highlight | | Substitute `pip install "skore[hub]"` / `"skore[mlflow]"` based on agent guess | Install variant comes from G-SKORE-MODE's recorded answer. `python-env-manager` reads that row, not agent intuition | | Silently change `skore mode:` mid-project to "fix" a broken init | Switching orphans existing reports. Always explicit `AskUserQuestion` first | | Hub substitution but leaving a directory-style `workspace=str(PROJECT_ROOT / "reports")` | In hub mode `workspace=` carries the **Hub workspace name** (e.g. `workspace="acme-corp"`), not an on-disk dir. mlflow rejects `workspace=` and uses `tracking_uri=`. Substitute the whole block, not just the mode literal | | mlflow substitution that keeps a `login(mode=...)` call | mlflow mode needs no skore login — auth is the MLflow server's concern. `login` belongs only to hub mode | | Local `workspace="reports"` (relative) instead of `str(PROJECT_ROOT / "reports")` (absolute) | Relative resolves against CWD; runs from other dirs write the store somewhere unexpected. Always absolute via `PROJECT_ROOT` | | Putting `skore.login(mode="hub")` after `skore.Project(...)` | `Project(...)` requires authenticated session in hub mode. `login` first | | Substituting `<SKORE_PROJECT_INIT>` in `audit/<stem>.py` independently of `experiments/<stem>.py` | Audit must open the same Project. Byte-identical copy from the experiment file is the rule | | Hub workspace name contains `/` (e.g. `acme/datasci`) | `workspace=` is a single Hub workspace identifier, not a path or a `<workspace>/<project>` join; a `/` is invalid. Reject at G-SKORE-MODE follow-up | | `project.get(key)` raised `KeyError` → re-run `evaluate` + `put` to "recover" | Lookup shape wrong (`get` is by id). Use `summarize()` → `get(id)` |

## Pre-flight — emit before any code

Each ticked box needs an Evidence line (format spec in `iterate-ml-experiment` § "Pre-flight evidence requirements"; see also `python-env-manager/references/preflight_evidence.md`).

``` Pre-flight (organize-ml-workspace): - [ ] `Workspace decisions` in `journal/JOURNAL.md` Status checked for pre-recorded gates (tabular, env_manager, package, skore mode) Evidence: lists each <gate>: <value | not recorded> | "n/a — JOURNAL.md does not exist yet (truly fresh)" - [ ] Tier 1 mandatory libs importable: sklearn, skrub, skore Evidence: Write scratch/<ts>_check_tier1.py + `pixi run python …` output. **Inline `python -c` is NOT evidence**. - [ ] Layout detection done: <existing | fresh> Evidence: ls/Glob on project root + matched signal from Detection - [ ] G-TABULAR resolved: pandas | polars Evidence: AskUserQuestion id=<id> via data-science-python-stack | JOURNAL.md Status (Workspace decisions) | user quote turn N - [ ] G-ENV

--- name: organize-ml-workspace description: > Decide where files live in an ML experimentation project: reusable code in `src/<pkg>/`, one `# %%` script per experiment in `experiments/`, design notes + index in `journal/`, reports in `reports/`, agent-only probes in `scratch/`. Owns the layout, the file-creation rules (one file per experiment, ask before editing), and the jupytext `# %%` script convention. Never imposes `data/` — the user owns that.

TRIGGER — any of: - Starting a new ML project / scaffolding a workspace. - About to create the first experiment file in a project. - About to create `src/<pkg>/data.py` / `features.py` / `pipeline.py` / `evaluate.py` for the first time. - About to write a `.ipynb` for experimentation — redirect to a `# %%` script under `experiments/`. - User asks where something should live, how to organize the project, or how to set up the workspace. - About to add a new experiment iteration — decide new file vs edit existing (ask the user).

SKIP when: the file is clearly part of an already-populated module (e.g., adding a function to existing `features.py`); pure refactor inside a single existing file; pipeline declaration mechanics (`build-ml-pipeline`); evaluation mechanics (`evaluate-ml-pipeline`); skore symbol lookup (`python-api`).

HOW TO USE: **first run the Detection table** below — if any signal matches, glue to existing conventions (do not rename or move folders). If no signal matches, scaffold the default layout. **Emit the Pre-flight checklist as visible text and read the Stop conditions before any file is created or edited.** Use templates in `templates/`; copy and adapt, do not rewrite from scratch. ---

# Organize ML Workspace

Where things live, when to create a new file, what each file is allowed to contain.

## Next-step pointers — where you go after this skill

| You came here for… | → next | |---|---| | Bootstrap a fresh workspace | → `python-env-manager` § Bootstrap; then `iterate-ml-experiment` § 0 | | First experiment script | → `iterate-ml-experiment` § 0 for the design note | | Add a new experiment iteration | → `iterate-ml-experiment` § 1 (new vs edit decision) | | Pipeline / evaluate / smoke-test content | → `build-ml-pipeline` / `evaluate-ml-pipeline` / `smoke-test-ml-pipeline` |

Always re-emit the Pre-flight checklist with evidence before declaring the turn done.

## Sibling skills — open just-in-time

Don't pre-read every sibling at session start (paralysis). Open each sibling SKILL.md when a step calls for it (e.g. open `python-env-manager` before G-ENV-MGR; open `iterate-ml-experiment` before handing off the design-note write). Emit this tracker once per turn:

``` Sibling skills (just-in-time): - data-science-python-stack, python-env-manager, python-api, python-code-style, iterate-ml-experiment, explore-ml-data, build-ml-pipeline, evaluate-ml-pipeline, test-ml-pipeline, smoke-test-ml-pipeline ```

## Stop conditions — read before anything else

- **Missing dependency.** If `import skore` raises, STOP. Invoke `python-env-manager` for the install command. Do not drop `skore.Project` in favor of `mlflow` / pickles / "print metrics" — the workspace contract assumes a Project on disk. - **Symbol from memory is forbidden.** Any `skore.Project` / `project.put` / `skore.evaluate` signature must come from a `python-api` call this turn. - **Existing layout wins — detect first.** Run the Detection table before scaffolding. Don't rename, relocate, or "tidy up" existing folders. - **Notebooks are not silent.** Existing `.ipynb` files in the experiment folder → surface the convention shift and ask. Don't auto-convert. - **Scratch is read-only against the skore Project.** Probes under `scratch/<ts>_<short>.py` may call `project.get(...)`, `project.summarize()`, walk an existing report. They MUST NOT call `skore.evaluate(...)` or `project.put(...)`. When `project.get(key)` raises `KeyError`, the fix is the lookup shape: `get` is by **id**, not by `key`. Use `summarize()` → `(key, id)` → `get(id)`. Never substitute by re-running `evaluate` + `put`. - **Tabular library is asked, not assumed (G-TABULAR).** Pandas being importable via skore is not a pick. Invoke `data-science-python-stack` for the structured ask. Free-text ("quick", "you pick") does NOT resolve. Persisted in JOURNAL.md Status `Workspace decisions`. - **Package name is asked, not inferred (G-PKG-NAME).** Before any `pyproject.toml` / manifest creation (including `pixi init` / `uv init` / `poetry init`), fire an `AskUserQuestion` for the `src/<pkg>/` import name. Folder name in snake_case is the default. **Manifest creation before G-PKG-NAME passes is forbidden** — running `init` first creates a `[project] name` entry, and reading "name is in the manifest" back is circular. If a manifest exists, confirm via `AskUserQuestion` — continuity from a prior session is not continuity from a user decision. - **Skore Project mode is asked, not assumed (G-SKORE-MODE).** Before any template instantiation containing `skore.Project(...)`, fire an `AskUserQuestion` for `local` | `hub` | `mlflow`. Default proposal: `local`. All three are always offered; a detected hub config in the CWD (`config.toml` / `SKH__*` / cached login) only influences the default, never prunes the choices. Hub triggers a follow-up for the workspace name (org/team on the hub — distinct from local-mode `workspace=`); mlflow triggers a follow-up for the **MLflow tracking server URI** (`tracking_uri=`) — the agent cannot infer it. Persists as `skore mode:` (+ `skore hub workspace:` when hub, + `skore mlflow tracking uri:` when mlflow). Without it the `<SKORE_PROJECT_INIT>` substitution has no shape to fill. Details: → `references/g_skore_mode.md`. - **Switching skore mode mid-project is forbidden by default.** Once recorded, do not silently change. A switch orphans every existing report in the prior store — skore has no built-in migration. Requires explicit `AskUserQuestion` confirmation surfacing the migration burden, then rewrite all `<SKORE_PROJECT_INIT>` blocks. Procedure: → `references/g_skore_mode.md` § "Switching mid-project". - **Env manager is asked, not assumed (G-ENV-MGR).** Hand off to `python-env-manager`. Pixi on PATH is detection, not permission. Don't run `pixi init` / `uv init` / `poetry init` until G-ENV-MGR has passed *in `python-env-manager`*. - **Harness "no clarifying questions" hints do NOT waive these gates.** G-TABULAR, G-PKG-NAME, G-ENV-MGR, G-SKORE-MODE, python-api consultation, new-vs-edit decision are operating-contract gates. "Quick" / "go fast" never waives them. - **Post-hoc audit — required before ending the turn.** Walk every pre-flight row; if any Evidence cell is unfilled, surface the non-compliance explicitly. Most common failure: "I scaffolded successfully so everything must be fine".

## Forbidden shortcuts

| Shortcut | Why it's wrong | |---|---| | `pixi` on PATH → run `pixi init` to get a manifest, then read the name back | Violates G-ENV-MGR (silent manager pick) AND G-PKG-NAME (name from folder via init side-effect). Circular: the agent created the manifest it now claims to read | | Folder name = good name → skip the ask | Default *value* is fine; silent *pick* is not. G-PKG-NAME requires the structured ask even with folder as default | | `pandas` already importable via skore → write `import pandas` in `data.py` | Transitive presence is not a pick. Violates G-TABULAR | | Scaffold every skeleton in one turn, incl. `experiments/01_baseline.py` body | Scaffold stops at empty `journal/` placeholder. Experiment script content lands after design-note approval (`iterate-ml-experiment` § 3) | | Scaffold drops `audit/01_baseline.py` at workspace creation | Audit files placed by `audit-ml-pipeline` at § 4 record-outcome. Empty `audit/` at scaffold is correct | | Forget `audit/` in the scaffold layout | Four-way stem pairing breaks | | `pyproject.toml` exists with `name = <x>` → reuse without confirming | Always re-confirm via G-PKG-NAME | | Batch G-TABULAR + G-PKG-NAME + G-ENV-MGR + G-SKORE-MODE into prose recommendations | The gates take structured `AskUserQuestion`. Prose followed by "let me know" does NOT resolve them | | Skip G-SKORE-MODE because templates use `mode="local"` | Templates carry the `<SKORE_PROJECT_INIT>` marker, not a literal. The gate must fire | | Pick `mode="hub"` without checking the workspace exists / user has access | Project init fails at first `put()` with an authorization error. Confirm during G-SKORE-MODE, not at execution time | | Pick `mode="mlflow"` and invent / default the `tracking_uri=` | The tracking URI is server-specific; the agent cannot infer it. Ask the user at the G-SKORE-MODE follow-up. No silent `http://localhost:5000` | | Folder has skore-hub config (`config.toml` / `SKH__*` / cached login) → present only `hub` (or `hub`+`local`), drop `mlflow` | Detected config is detection, not permission (cf. "Pixi on PATH"). The gate must always offer all three; config only sets the default highlight | | Substitute `pip install "skore[hub]"` / `"skore[mlflow]"` based on agent guess | Install variant comes from G-SKORE-MODE's recorded answer. `python-env-manager` reads that row, not agent intuition | | Silently change `skore mode:` mid-project to "fix" a broken init | Switching orphans existing reports. Always explicit `AskUserQuestion` first | | Hub substitution but leaving a directory-style `workspace=str(PROJECT_ROOT / "reports")` | In hub mode `workspace=` carries the **Hub workspace name** (e.g. `workspace="acme-corp"`), not an on-disk dir. mlflow rejects `workspace=` and uses `tracking_uri=`. Substitute the whole block, not just the mode literal | | mlflow substitution that keeps a `login(mode=...)` call | mlflow mode needs no skore login — auth is the MLflow server's concern. `login` belongs only to hub mode | | Local `workspace="reports"` (relative) instead of `str(PROJECT_ROOT / "reports")` (absolute) | Relative resolves against CWD; runs from other dirs write the store somewhere unexpected. Always absolute via `PROJECT_ROOT` | | Putting `skore.login(mode="hub")` after `skore.Project(...)` | `Project(...)` requires authenticated session in hub mode. `login` first | | Substituting `<SKORE_PROJECT_INIT>` in `audit/<stem>.py` independently of `experiments/<stem>.py` | Audit must open the same Project. Byte-identical copy from the experiment file is the rule | | Hub workspace name contains `/` (e.g. `acme/datasci`) | `workspace=` is a single Hub workspace identifier, not a path or a `<workspace>/<project>` join; a `/` is invalid. Reject at G-SKORE-MODE follow-up | | `project.get(key)` raised `KeyError` → re-run `evaluate` + `put` to "recover" | Lookup shape wrong (`get` is by id). Use `summarize()` → `get(id)` |

## Pre-flight — emit before any code

Each ticked box needs an Evidence line (format spec in `iterate-ml-experiment` § "Pre-flight evidence requirements"; see also `python-env-manager/references/preflight_evidence.md`).

``` Pre-flight (organize-ml-workspace): - [ ] `Workspace decisions` in `journal/JOURNAL.md` Status checked for pre-recorded gates (tabular, env_manager, package, skore mode) Evidence: lists each <gate>: <value | not recorded> | "n/a — JOURNAL.md does not exist yet (truly fresh)" - [ ] Tier 1 mandatory libs importable: sklearn, skrub, skore Evidence: Write scratch/<ts>_check_tier1.py + `pixi run python …` output. **Inline `python -c` is NOT evidence**. - [ ] Layout detection done: <existing | fresh> Evidence: ls/Glob on project root + matched signal from Detection - [ ] G-TABULAR resolved: pandas | polars Evidence: AskUserQuestion id=<id> via data-science-python-stack | JOURNAL.md Status (Workspace decisions) | user quote turn N - [ ] G-ENV