Jupyter notebooks agents can edit

# AGENTS.md: Jupyter notebooks

Data and ML work in Jupyter notebooks, managed with uv. Notebooks are paired with plain Python files by Jupytext and
committed without outputs.

## Editing notebooks
- Edit the paired `.py` file (Jupytext percent format, cells start with `# %%`), not the `.ipynb` JSON. Then sync:
  `uv run jupytext --sync notebooks/<name>.py`. Never hand-edit cell JSON, outputs or execution counts.
- New notebook: write `notebooks/<name>.py` in percent format and pair it:
  `uv run jupytext --set-formats ipynb,py:percent notebooks/<name>.py`.
- Keep outputs out of git: `nbstripout` is installed as a git filter (`uv run nbstripout --install`). Do not remove it.

## Done means it runs top to bottom
- Execute from a fresh kernel before reporting: `uv run jupytext --to ipynb --execute notebooks/<name>.py`
  (or `uv run jupyter nbconvert --to notebook --execute --inplace notebooks/<name>.ipynb`).
- A notebook that only works after running cells out of order is broken. Fix the order; no hidden state.
- Report the key numbers or the figure you produced, not just "it ran".

## Reproducibility
- Dependencies in `pyproject.toml` via `uv add`; no `!pip install` cells. Dev tools: `uv add --dev jupytext nbconvert
  ipykernel nbstripout` (executing needs nbconvert and ipykernel).
- One parameters cell near the top (paths, dates, sample sizes, seeds). No magic numbers further down.
- Seed every source of randomness (`numpy.random.default_rng(seed)`, framework seeds) and say so in the notebook.
- Paths relative to the project root; raw data in `data/raw/` is read-only and gitignored. Write outputs to
  `data/processed/` or `reports/`.
- Long training or heavy queries: move the code into a module in `src/` and import it; keep the notebook for narrative,
  checks and plots.

## Data care
- Look at the data before modelling: shape, dtypes, missing values, duplicates, a few rows. Use the
  `notebook-change` skill.
- Never print or commit personal data, credentials or full raw tables. Use `.head()` on synthetic or anonymised data.
- Split train and test before any fitting or scaling. Never tune on the test set.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `notebook-change`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Jupyter notebooks agents can edit" v1.0.0 — https://loadout.jnw-it.com/loadouts/jupyter-notebooks/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `notebook-change`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Jupyter notebooks agents can edit" v1.0.0 — https://loadout.jnw-it.com/loadouts/jupyter-notebooks/ -->

---
name: notebook-change
description: Change or add a Jupyter notebook through its Jupytext-paired .py file, check the data first, run it top to bottom in a fresh kernel and keep outputs out of git. Use for any notebook work.
---

# Notebook change

1. Find the paired `.py` file for the notebook (`jupytext --paired-paths notebooks/<name>.ipynb` if unsure). If the
   notebook is not paired yet, pair it first and commit that as its own change.
2. Read the parameters cell and the cells you will change. Edit the `.py` file only, keeping `# %%` cell markers and
   `# %% [markdown]` cells for narrative.
3. When data is involved, add or keep a check cell like the one in `references/analysis.py`: shape, dtypes, missing
   values and duplicates, with `assert` lines for what the rest of the notebook relies on.
4. Sync and execute from a fresh kernel: `uv run jupytext --sync notebooks/<name>.py` then
   `uv run jupytext --to ipynb --execute notebooks/<name>.py`. Fix any error and run again from the top.
5. Check git sees no outputs: `git diff --stat` shows the `.py` and a small `.ipynb` change; if outputs appear, run
   `uv run nbstripout notebooks/<name>.ipynb` and check the filter is installed.
6. Report: what changed, the key result (numbers or a figure described in words), and the run time.

# ---
# jupyter:
#   jupytext:
#     formats: ipynb,py:percent
#   kernelspec:
#     display_name: Python 3
#     language: python
#     name: python3
# ---

# %% [markdown]
# # Weekly orders: example analysis
# Parameters first, a data check, then the result. Runs top to bottom from a fresh kernel.

# %% tags=["parameters"]
SEED = 42
N_ORDERS = 500
WEEKS = 8

# %%
import random
import statistics

rng = random.Random(SEED)
orders = [{"week": rng.randrange(WEEKS), "pence": rng.randint(200, 5000)} for _ in range(N_ORDERS)]

# %% [markdown]
# ## Data check
# Shape, missing values and ranges that the rest of the notebook relies on.

# %%
assert len(orders) == N_ORDERS, "unexpected row count"
assert all(o["pence"] is not None for o in orders), "missing values"
assert all(0 <= o["week"] < WEEKS for o in orders), "week out of range"
print(f"rows: {len(orders)}, weeks: {len({o['week'] for o in orders})}")

# %%
by_week = {w: [o["pence"] for o in orders if o["week"] == w] for w in range(WEEKS)}
summary = {w: (len(v), statistics.median(v)) for w, v in by_week.items()}
busiest = max(summary, key=lambda w: summary[w][0])
print(f"busiest week: {busiest} with {summary[busiest][0]} orders, median £{summary[busiest][1] / 100:.2f}")