/kaggle

name: kaggle
description: "Generate a Kaggle competition notebook as a Jupytext `# %%` Python script following the user's established ML research style: PTL for DNN training, best-fit tool selection, EDA→Baseline→Train→Inference pipeline with per-stage lens cells, small single-purpose cells each carrying a why. Grounds data schema and submission format through the authenticated `kaggle` CLI (file listing, sample submission, leaderboard) rather than the login-walled competition page. Tuned to win (leakage-safe CV, metric-aligned modeling) as much as to teach. Writes output to .experiments/kaggle/<name>.py. Requires foundry plugin (foundry:sw-engineer, no fallback)."
argument-hint: <competition-name> [<url-or-description>] [--type classification|regression|segmentation|detection|tabular] [--eda-only] [--inference-only] [--offline-setup] [--resume <existing.py>] [--keep "<items>"]
allowed-tools: Read, Write, Bash, Glob, Agent, WebFetch, AskUserQuestion, TaskCreate, TaskUpdate, TaskList
disable-model-invocation: true
effort: xhigh

<objective>

Generate Kaggle competition notebook script, Jupytext `# %%` format.

Two goals, equal weight — neither traded for other:

• **Win** — leaderboard-competitive: leakage-safe CV, metric-aligned loss/model choice, tuning/ensembling when it moves the score, not style theater
• **Teach** — read top to bottom like a university/seminar lecture on solving this competition: reader new to it follows the full reasoning chain, every decision motivated, nothing left as unexplained code

Follows user's ML research style distilled from past notebooks:

• **PTL always for DNN training** (PyTorch Lightning + torchmetrics) — even simple baselines
• **Tool agnostic** — best-fit library for problem; PTL when training loop needed
• **Stages with lenses** — each major stage: quick sanity check cell (show one batch, print shapes, verify submission format)
• **Small, single-purpose cells** — one action per cell (load, one transform, one plot, one check); never bundle setup + run + verify to save cell count
• **Every cell earns its place** — one-line why (comment or markdown sentence) before/in each cell: the specific reason this step happens now — never a restatement of what the code does
• **Section markdown is extensive and structured** — full explanation of what/why/how-it-advances-the-goal per section, formatted as tables/lists/blockquotes over dense prose paragraphs; markdown before a plot sets up the question, markdown after states the finding and its implication — plot and prose flow as one beat, never an orphaned chart
• **`# !` inline / `%%bash` cell over subprocess** — single command: `# ! head submission.csv`; multi-command chain (installs, `nvidia-smi` + `ls -lh`) → dedicate cell to `%%bash` instead of stacking `# !` lines
• **EDA is visual** — distribution plots, sample grids, dimension scatters before any model
• **Inference included** — model save pattern + separate load-and-infer cells
• **CSVLogger + seaborn** — metrics plotted from `metrics.csv` after every training run

NOT for writing Python packages, modules, production code — notebook scripts only, unless the user opts into the Step 4 package-distillation gate. NOT research literature survey — use `/research:topic` for SOTA literature search.

</objective>

<inputs>

• **$ARGUMENTS**: one of:
• `<competition-name>` — short slug for output filename; generates blank template
• `<competition-name> <url>` — fetches competition overview from URL before generating
• `<competition-name> "<description>"` — inline description of problem and data
• `--type <type>` — hint: `classification`, `regression`, `segmentation`, `detection`, `tabular` (auto-detected when omitted)
• `--eda-only` — generate only EDA sections (no model/training/submission); always online (no offline setup)
• `--inference-only` — generate inference notebook from checkpoint (no EDA, no training); always offline (frozen packages pattern); loads checkpoint from `PATH_CHECKPOINT` constant; output suffix `-inference.py`
• `--offline-setup` — include offline package setup (frozen_packages pattern) in setup cell; auto-applied when `--inference-only`; ignored when `--eda-only` (EDA always online)
• `--resume <path>` — read existing `.py` script, extend/improve it

Output: `.experiments/kaggle/<competition-name>.py`. Step 4's opt-in package-distillation gate additionally writes `src/<package>/<module>.py`, `tests/test_<module>.py`, and `notebooks/01_<competition-name>_pkg.py`.

</inputs>

<constants>

OUTPUT_DIR:       .experiments/kaggle/
DATA_DIR:         .experiments/kaggle/data/<competition>/  # kaggle CLI downloads land here, gitignored
CELL_MARK:        "# %%"
MD_CELL_MARK:     "# %% [markdown]"
COMPETITORS_DIR:  resources/competitors/  # optional user-project path, not shipped in plugin — Step 1 reads if present
# NOTE: doc-only — not shell vars across Bash() calls (state doesn't persist); keep synced with literal use sites (Steps 1,3,4)

</constants>

<compaction>

• Key boundary: end of Step 3 — notebook script generated by `foundry:sw-engineer`, written to OUTFILE.
• Preserve: OUTFILE path (derived from TMPDIR keys), COMPETITION_NAME (TMPDIR key), mode flags (EDA_ONLY, INFERENCE_ONLY, OFFLINE_SETUP).
• Clear at Step 1 start (stale prior run) and after Step 4 package-distillation gate resolves.

</compaction>

<workflow>

**Task hygiene** — follow CLAUDE.md §Task Management for deferred task tools, initial TaskList triage and task update sequencing.

<!-- ../../assets/images/kaggle-arch.svg diagrams the runs, gates and parallel fan-out. Documentation only, never loaded — update it in the same commit as any change to step order, gate placement, or agent fan-out. -->

Step 1: Parse arguments and gather context

# loads: compaction-contract.md
PLUGIN_ROOT=$(python "${CLAUDE_PLUGIN_ROOT}/bin/resolve_plugin_root.py" --plugin-name research) || exit $?; export PLUGIN_ROOT
export CSID="${CLAUDE_CODE_SESSI