python-code-style

--- name: python-code-style description: > Owns Python code style for this stack: ruff for lint + format, numpydoc for docstrings. Three responsibilities — (1) place the project's `ruff.toml` from the bundled template once the stack and workspace are in place, (2) run ruff against any Python files Claude has just generated or edited, and (3) contextualize each touched file's comments to the data-science problem — rewriting any leftover template / workflow prose (skill names, gates, runner, digest, guard-rails) into concise, problem-specific docs so the user's committed files read like a colleague wrote them, not like a generated scaffold. Stops at "the touched files pass `ruff check` and document the problem, not the process."

TRIGGER when (any of these): (1) a Python file was just created or edited via Write / Edit / MultiEdit — invoke this skill before declaring the task done so ruff is run AND the file's comments are contextualized to the problem; (2) a fresh ML workspace was just scaffolded by `organize-ml-workspace` and the project has no `ruff.toml` at its root yet — drop the bundled template; (3) the user asks about lint, format, docstring style, or reaches for `black` / `isort` / `flake8` / `pydocstyle` (redirect to ruff — the stack's canonical linter, owned by `data-science-python-stack` Tier 1).

SKIP when: the project is non-Python; the only edits in this turn are to Markdown / TOML / JSON / YAML; the file lives in a third-party vendored directory the user doesn't own.

HOW TO USE: run ruff manually on the files you just touched — do not configure a PostToolUse hook for this. **Read the "Stop conditions" block and emit the Pre-flight checklist as visible text in your response — both are mandatory before running ruff.** ---

# Python Code Style

Single owner of "what does well-styled Python look like in this stack": ruff (lint + format) and numpydoc docstrings. This skill is explicitly **manual** — Claude runs ruff on the files it has just touched, no hook involved.

## Stop conditions — read before anything else

- **Do not configure a PostToolUse / PreToolUse hook for ruff.** This skill is intentionally manual. A hook tightens the loop in ways that bite (every micro-edit triggers a fix cycle, partial files fail D-rule checks mid-write, retries can stall the turn). If the user explicitly asks for an automated hook later, redirect to `update-config` — but the default is "Claude runs ruff itself." - **Do not substitute ruff with `black` / `isort` / `flake8` / `pydocstyle` / `pylint`.** Ruff is the canonical linter in this stack (`data-science-python-stack` Tier 1). If `import ruff` / `pixi run ruff --version` fails, route through `python-env-manager` to install — don't silently fall back. - **One fix attempt per file, then surface.** If `ruff check` reports issues after Claude's first fix, address them once. If the *same* issue persists after the second pass, stop editing that file and surface the remaining diagnostics + diff to the user. This is the anti-infinite-loop guardrail — do not enter a third cycle on the same warning. - **Don't lint files outside the user's code.** The hook scope is `src/<pkg>/`, `experiments/`, `audit/`, `data/eda.py` (the explore-ml-data EDA script), top-level `*.py` scripts, and any package directory the user owns. Skip vendored paths, generated files, the rest of user-owned `data/`, and anything under `.pixi/`, `.venv/`, `node_modules/`, etc. - **Never write `ruff.toml` from memory.** The bundled `templates/ruff.toml` is the single source of truth — it encodes the per-file ignores (`experiments/**`), the numpydoc convention, and the rule selection this stack expects. Initial setup requires **`Read .agents/skills/python-code-style/templates/ruff.toml`** *this turn*, then `Write <project-root>/ruff.toml` verbatim from that file's content. Authoring a custom `ruff.toml` from training- data memory drops half the contract silently. If you catch yourself typing `[lint]` / `[format]` / `select = [...]` without having read the template this turn, STOP and `Read` it first. - **Don't call `warnings.filterwarnings(...)` unless the user explicitly asks for it.** Same for `warnings.simplefilter`, `@pytest.mark.filterwarnings`, and `filterwarnings = [...]` in `pytest.ini` / `pyproject.toml`. Warnings are signal in this stack. - **Documentation describes the problem, not the workflow.** A committed file's module docstring, header, and comments must describe the **data-science problem** and the file's role in it — never the skills, the gates (`G-*`), the cell runner, the run digest, the journal / backlog / design-note machinery, or "the process we are following". That guidance is agent-facing and lives in the skills, not in the user's files. When you touch a file that now carries **real content**, rewrite any leftover generic template or workflow prose into concise, problem-specific docs grounded in the current context (the project goal, the experiment's hypothesis, the dataset). If the file is still an empty skeleton (no content / no context yet), leave its placeholder — the contextualization happens when the content lands. Details: § "Contextualize the comments".

## Pre-flight — emit this checklist as visible text before running ruff

``` Pre-flight (python-code-style): - [ ] ruff importable in the project's env (`pixi run ruff --version` succeeds, per `data-science-python-stack` Tier 1) - [ ] `ruff.toml` present at project root. If absent AND stack + workspace are already set up: the bundled template MUST be read **this turn** before being written verbatim. Evidence: Read .agents/skills/python-code-style/templates/ruff.toml (this turn) + Write <project-root>/ruff.toml (this turn) | "n/a — ruff.toml already at project root" **Inline-authored ruff.toml from memory is NOT evidence.** - [ ] File list ready: <abs paths of .py files touched this turn> - [ ] Decision recorded: this is the first ruff pass on these files (proceed) | second pass (proceed but stop on persistent issues) | third pass on same warning (STOP, surface to user) - [ ] One-fix-per-file rule acknowledged: max two passes per warning, then surface remaining diagnostics + diff to the user. - [ ] Comments contextualized: each touched file with real content has problem-specific docs and NO workflow/skill/gate/runner/digest meta (§ "Contextualize the comments") Evidence: per file, "rewrote header to <problem context>" | "no leftover template/workflow prose" | "n/a — empty skeleton, no context yet" ```

## Scope

- **In scope:** running `ruff format` + `ruff check --fix` + `ruff check` on Python files Claude has just generated or edited; authoring numpydoc docstrings on public functions and classes; contextualizing each touched file's comments to the data-science problem and stripping workflow/process meta (§ "Contextualize the comments"); dropping the `ruff.toml` template into a fresh project. - **Out of scope:** type hints (mypy / pyright are not in the stack); naming conventions ruff doesn't enforce; setting up PostToolUse / PreToolUse hooks; linting non-Python files.

## What to run, in what order

For every Python file touched this turn (call them `<files>`), run inside the project's environment manager — `pixi run` for pixi projects, equivalent for uv / poetry / conda (per `python-env-manager`):

```bash pixi run ruff format <files> pixi run ruff check --fix <files> pixi run ruff check <files> ```

Three steps, in order:

1. **`ruff format`** — applies the formatter (line length, quoting, trailing commas, blank lines around defs). Idempotent. 2. **`ruff check --fix`** — auto-fixes everything ruff knows how to fix in place: import sorting (`I`), legacy syntax (`UP`), detectable bug patterns (`B`). 3. **`ruff check`** (no `--fix`) — final pass. Anything reported here needs Claude's attention: missing docstrings (`D`), undefined names (`F`), code structure issues. Address them, then re-run the trio. Apply the **one-fix-per-file rule** from Stop conditions.

If a file under `experiments/` or `audit/`, or the `data/eda.py` EDA script, has a `D100` ("missing module docstring") or `D103` ("missing function docstring") warning, that's expected for `# %%` cells; the bundled `ruff.toml` per-file-ignores `D100` + `D103` (and `E402`, `B018`) for `experiments/**`, `audit/**`, and `data/eda.py`. If you're seeing them, the `ruff.toml` isn't loaded — check that it lives at the project root.

Audit files (`audit/<NN>_<short_name>.py`, owned by `audit-ml-pipeline`) and the EDA script (`data/eda.py`, owned by `explore-ml-data`) lint the same way as experiment files: same `# %%` cell convention, same per-file ignores, same NumPyDoc convention for any helper functions. After writing or editing one of these files, run the same trio (`ruff format` → `ruff check --fix` → `ruff check`).

## Contextualize the comments

ruff makes a file *well-formed*; this pass makes it *well-documented for the problem*. Templates ship with neutral placeholders and a little authoring scaffolding so the generating skill knows what each cell / module is for. None of that should survive into the user's committed file — the user's files document the **data-science problem**, not the process that produced them.

After the ruff trio, for every touched file that now carries **real content**, do a quick documentation pass:

1. **Fill the header for this problem.** Replace any `<placeholder>` or generic header with a one- or two-line description of what this file does *here*: the experiment's hypothesis (`experiment.py`), what this module contributes to the pipeline (`src/<pkg>/*.py`), which report this file reviews and what it tests (`audit/<stem>.py`), what the dataset is and what the analysis looks at (`data/eda.py`). Pull the wording from the live context — the project goal, the approved design note, the dataset. 2. **Strip the workflow meta.** Delete leftover process commentary: skill names, gate IDs (`G-*`), `§` cross-references, "the agent", "the (cell) runner", "the digest", "run cell by cell", journal / backlog / sourcing jargon, and inline guard-rails like "MUST NOT call `put` / bare expressions, don't `print`". Those guard-rails stay enforced — they live in the owning skill's SKILL.md, which is where the agent reads them, not in the user's file. 3. **Keep the substance.** Genuinely useful problem / engineering context and the numpydoc docstrings stay. Cell markers (`# %%`) and any remaining `<...>` placeholders the agent still has to fill stay until they are filled.

The result should read like a colleague wrote the file for this project — not like a generated scaffold. Skip a file that is still an empty skeleton (e.g. a freshly scaffolded `src/<pkg>/*.py` with no body yet): there is no context to write about until the content lands, and the contextualization happens on the edit that fills it.

This pass is **owned here** so the rule is enforced uniformly. Every file-writing skill already hands off to this skill after a write; that hand-off now also covers contextualizing the comments.

## Numpydoc — the docstring convention

Public functions and classes carry numpydoc-format docstrings; ruff's `D` rules with `pydocstyle.convention = "numpy"` enforce the shape.

**A bare one-line summary is NOT sufficient for public functions.** The `Parameters` / `Returns` (and `Raises` when applicable) sections are mandatory — even when the function is small, even when the user says "just the summary is fine". Approving a one-line docstring on a public function silently fails the contract this skill enforces; the function looks `D`-rule-clea