/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. Tuned to win (leakage-safe CV, metric-aligned modeling) as much as to teach. Writes output to .experiments/kaggle/<name>.py."
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: high

<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/
CELL_MARK:     "# %%"
MD_CELL_MARK:  "# %% [markdown]"
# NOTE: documentation-only — not referenced as shell vars across separate Bash() calls (state doesn't persist); keep values in sync 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}"
ARGS="$ARGUMENTS"
COMPETITION_NAME=$(echo "$ARGS" | awk '{print $1}')
RESUME_FLAG=""
EDA_ONLY=false
INFERENCE_ONLY=false
OFFLINE_SETUP=false
PROBLEM_TYPE=""

[[ "$ARGS" == *"--eda-only"* ]]      && EDA_ONLY=true
[[ "$ARGS" == *"--inference-only"* ]] && INFERENCE_ONLY=true
[[ "$ARGS" == *"--offline-setup"* ]]  && OFFLINE_SETUP=true
[[ "$ARGS" =~ --type[[:space:]]([a-z]+) ]] && PROBLEM_TYPE="${BASH_REMATCH[1]}"
[[ "$ARGS" =~ --resume[[:space:]]([^[:space:]]+) ]] && RESUME_FLAG="${BASH_REMATCH[1]}"

# inference always offline; EDA always online (overrides --offline-setup)
[ "$INFERENCE_ONLY" = "true" ] && OFFLINE_SETUP=true
[ "$EDA_ONLY" = "true" ]       && OFFLINE_SETUP=false

echo "Competition: $COMPETITION_NAME"
echo "Type: ${PROBLEM_TYPE:-auto-detect}"
echo "EDA only: $EDA_ONLY | Inference only: $INFERENCE_ONLY | Offline setup: $OFFLINE_SETUP"

# Persist for Steps 3+4 (bash state lost across Bash() calls)
echo "$COMPETITION_NAME" > "${TMPDIR:-/tmp}/kaggle-competition-name-${CSID}"
echo "$EDA_ONLY"         > "${TMPDIR:-/tmp}/kaggle-eda-only-${CSID}"
echo "$INFERENCE_ONLY"   > "${TMPDIR:-/tmp}/kaggle-i