/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, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch, 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
• **`# !` bash over subprocess** — package installs, `nvidia-smi`, `ls -lh`, `# ! head submission.csv`
• **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. 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`

</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**: call `TaskList` first; close orphaned tasks. Create tasks per phase.

Step 1: Parse arguments and gather context

# loads: compaction-contract.md
export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
python "${CLAUDE_PLUGIN_ROOT:-plugins/cc_research}/bin/parse_kaggle_args.py" -- "$ARGUMENTS"  # timeout: 5000 — mode flags + keep-items; persists sentinels for Steps 3+4, clears a stale contract

**Flag mutual-exclusion check** — if `EDA_ONLY` and `INFERENCE_ONLY` are both `true` (both `--eda-only` and `--inference-only` passed): print `` ! Conflicting flags: `--eda-only` and `--inference-only` are mutually exclusive (`--eda-only` is always-online with no training; `--inference-only` is always-offline/frozen-package with no EDA — see `foundation.md`). Pick one. `` then invoke `AskUserQuestion` — (a) **Abort** · (b) **Continue ignoring both** (falls back to full mode: neither e