Add a Ruff 0.16 skill

README.md

@@ -54,7 +54,7 @@ ______________________________________________________________________
 
 ## Features
 
-- One router, six language skills, and four domain or quality skills.
+- One router, six language skills, and five domain or quality skills.
 - Short `SKILL.md` files, with references for the longer comparison material.
 - Coverage for typing (PEP 612, PEP 695, PEP 696, PEP 698, PEP 742),
   exceptions and logging (Ruff TRY/BLE/EM/LOG/N818/PERF203/B017),
@@ -64,6 +64,9 @@ ______________________________________________________________________
 - Verification skills covering selection plus deep dives for
   `hypothesis`, `crosshair`, and `mutmut`.
 - Quality-tool skill for `deadcode`, `pyscn`, and Pyinstrument.
+- Ruff 0.16 skill covering the 413-rule default set, `ruff: ignore`
+  suppression comments, Markdown formatting, and every settings, CLI,
+  and rule change since 0.14.0 — the material most models predate.
 
 ______________________________________________________________________
 
@@ -78,6 +81,8 @@ ______________________________________________________________________
 - [Python router](skills/python-router/SKILL.md) — the main entry point.
 - [Types and APIs](skills/python-types-and-apis/SKILL.md) — generics,
   `TypeVar`, `ParamSpec`, `TypeIs`, overloads, typed kwargs.
+- [Ruff 0.16](skills/ruff-016/SKILL.md) — default rule set, suppression
+  comments, Markdown formatting, settings and rule deltas.
 
 ______________________________________________________________________
 
@@ -93,7 +98,10 @@ of [Hypothesis](https://github.com/HypothesisWorks/hypothesis),
 [mutmut](https://github.com/boxed/mutmut); the quality-tool skill leans
 on [`deadcode`](https://github.com/albertas/deadcode),
 [`pyscn`](https://github.com/ludo-technologies/pyscn), and
-[Pyinstrument](https://github.com/joerick/pyinstrument).
+[Pyinstrument](https://github.com/joerick/pyinstrument). The Ruff skill
+draws on the [v0.16.0 release notes](https://astral.sh/blog/ruff-v0.16.0)
+and the changelogs, settings schema, and rule registry in
+[`astral-sh/ruff`](https://github.com/astral-sh/ruff).
 
 ______________________________________________________________________
 

docs/skill-catalogue-status.md

@@ -48,6 +48,11 @@ input or supporting material.
   References: `selection-matrix.md`.
 - `python-quality-tools` — `deadcode`, `pyscn`, and Pyinstrument.
   References: `deadcode-and-pyscn.md`, `pyinstrument.md`.
+- `ruff-016` — Ruff 0.16: the 413-rule default set, `ruff: ignore` and
+  `ruff: file-ignore` suppression, Markdown code-block formatting, and
+  the settings, CLI, and rule deltas across 0.14.x–0.16.0.
+  References: `default-rule-set.md`, `suppression-comments.md`,
+  `settings-and-cli.md`, `rule-and-version-delta.md`.
 
 ### Verification deep dives
 
@@ -78,6 +83,14 @@ input or supporting material.
 - `../rust-skill.worktrees/skill-refresh/` — the Rust catalogue this
   one is modelled on. Format and routing conventions match.
 
+## Maintenance
+
+- `ruff-016` is version-pinned material. Revisit it when Ruff 0.17
+  ships: check the default rule count, which preview rules stabilised,
+  and whether new settings appeared in `ruff.schema.json`. The counts
+  in `default-rule-set.md` were taken from the published default-rules
+  page for 0.16.0.
+
 ## Open questions
 
 - Whether to add a `python-pyproject` skill mirroring the Rust

docs/users-guide.md

@@ -52,6 +52,7 @@ The router asks a short question list and resolves to a single skill:
 - *Verification adversary selection* → `python-verification`, then load
   one of `hypothesis`, `crosshair`, or `mutmut`.
 - *Dead code, clones, profiling* → `python-quality-tools`.
+- *Ruff configuration, defaults, suppression, or upgrade* → `ruff-016`.
 
 Pairing rules:
 
@@ -92,6 +93,28 @@ cadences.
   is "where does the time go?". Use to find hot paths; use
   `pytest-benchmark` to regression-test them.
 
+## When to reach for the Ruff skill
+
+`ruff-016` covers Ruff as a tool rather than any one rule family.
+
+- **Upgrading.** Ruff 0.16.0 raised the default rule set from 59 to
+  413, started formatting Python blocks in Markdown files, and made
+  fields in the JSON output nullable. An upgrade needs a plan, not a
+  version bump.
+- **Configuration review.** Whether `select`, `ignore`, and
+  `per-file-ignores` still say what the project means under the new
+  defaults, and which of the settings added since 0.14.0 apply.
+- **Suppression.** `ruff: ignore`, `ruff: file-ignore`, and
+  `ruff: disable`/`enable` versus `noqa`, plus `--add-ignore` and the
+  `RUF100`–`RUF106` hygiene rules.
+- **"Does this rule exist yet?"** The reference tables record what
+  stabilised in 0.15.0 and 0.16.0 and what is still preview — material
+  that postdates most models' training data.
+
+Rule-level questions about exceptions and logging stay with
+`python-errors-and-logging`; its `ruff-rule-map.md` reference is the
+decision surface for TRY, BLE, EM, LOG, `N818`, and `PERF203`.
+
 ## Common pitfalls
 
 - Loading two language skills in one turn. Pick the one whose

skills/python-router/SKILL.md

@@ -41,6 +41,8 @@ follow-on skill.
   deep dives in `hypothesis`, `crosshair`, `mutmut`
 - Dead-code detection, clone and complexity scans, or profiling:
   `python-quality-tools`
+- Ruff configuration, rule selection, suppression comments, the 0.16
+  default rule set, or an upgrade from 0.14/0.15: `ruff-016`
 
 ## Pairing rules
 
@@ -53,6 +55,9 @@ follow-on skill.
   `python-iterators-and-generators` with `python-types-and-apis`.
 - Verification work loads `python-verification` first to choose the tool,
   then exactly one of `hypothesis`, `crosshair`, or `mutmut`.
+- Ruff rule questions about exceptions and logging (TRY, BLE, EM, LOG)
+  belong to `python-errors-and-logging`; `ruff-016` covers configuration,
+  defaults, suppression, and version deltas.
 
 ## Escalate when
 

skills/python-router/references/routing-matrix.md

@@ -21,6 +21,10 @@ Use this when the router's question list does not resolve to one skill.
 | Tests pass but mutants survive                 | `mutmut`                            | `python-testing`                |
 | Unused symbols and unreachable branches        | `python-quality-tools`              | —                               |
 | Hot loop too slow                              | `python-quality-tools`              | `python-iterators-and-generators` |
+| Ruff upgrade floods CI with new diagnostics    | `ruff-016`                          | —                               |
+| `select` / `ignore` list needs a rewrite       | `ruff-016`                          | `python-errors-and-logging`     |
+| `noqa` vs `ruff: ignore` in new code           | `ruff-016`                          | —                               |
+| `ruff format` reflowed Markdown unexpectedly   | `ruff-016`                          | —                               |
 
 ## Anti-routing
 
@@ -31,3 +35,6 @@ Use this when the router's question list does not resolve to one skill.
   surface dominates.
 - Do not load any deep dive without first reading the relevant selector
   skill (`python-verification`).
+- Do not load `ruff-016` to explain a single diagnostic whose family is
+  already covered by a language skill; load it when the question is about
+  Ruff itself — configuration, defaults, suppression, or a version delta.

skills/ruff-016/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: ruff-016
+description: "Use for Ruff 0.16 — the 413-rule default set, `ruff: ignore` and `ruff: file-ignore` suppression comments, Markdown code-block formatting, and the settings, CLI, and rule changes introduced across 0.14.x, 0.15.x, and 0.16.0. Load when upgrading Ruff, writing or reviewing `[tool.ruff]` configuration, or when a Ruff behaviour looks unfamiliar."
+globs: ["**/pyproject.toml", "**/ruff.toml", "**/.ruff.toml", "**/*.py", "**/*.pyi"]
+---
+
+# Ruff 0.16
+
+Ruff 0.16.0 (2026-07-23) is the largest behavioural break since 0.1: the
+default rule set went from 59 rules to 413, the formatter now touches
+Markdown files, and `noqa` has a first-class Ruff-native alternative.
+Treat any pre-0.16 mental model of "what Ruff does out of the box" as
+wrong.
+
+**Assume your training data predates most of this.** Ruff 0.15.0 shipped
+2026-02-03 and 0.16.0 shipped 2026-07-23; both are after the December
+2025 cut-off of most current frontier models. Check
+`ruff --version` before advising, and prefer the version-delta reference
+over recollection.
+
+## Working stance
+
+- Read the project's `[tool.ruff]` or `ruff.toml` before proposing rule
+  changes. On 0.16 an empty config is no longer a near-empty rule set.
+- An upgrade to 0.16 is a code change, not a tooling bump. Expect a
+  large diff on first run, and land it separately from feature work.
+- Do not paper over the new defaults with a blanket `ignore` list. Pick
+  either the old selectors or the new defaults, deliberately.
+- Prefer `ruff: ignore[RULE]` over `noqa: RULE` in new code on 0.16;
+  it is Ruff-specific, covers logical lines, and carries a reason.
+- Never invent rule codes. If unsure a code exists, run
+  `ruff rule <code>` (0.15.17+ also accepts rule names).
+
+## The three changes that break builds
+
+1. **Default rule set: 59 → 413.** `select` now defaults to a broad set
+   spanning 34 linters, including `I001` (import sorting), `F401`,
+   `UP006`/`UP007`/`UP045` (PEP 585/604 annotation rewrites), `B008`,
+   `SIM102`, `RUF012`, and `RUF013`. Notably *absent*: `E501`, the
+   `E711`–`E743` comparison and ambiguity rules, `D1xx` docstring
+   requirements, `ANN`, `ARG`, `S101`, `TRY003`, `EM101`, `COM812`,
+   `Q000`, and `PLR0913`.
+   See [default-rule-set.md](references/default-rule-set.md).
+2. **`ruff format` formats Markdown.** Python code blocks in `.md`
+   files are formatted by default, and `.md` files are discovered by
+   default. Opt out with `extend-exclude = ["*.md"]`.
+3. **JSON output can contain `null`.** `filename`, `location`,
+   `end_location`, and `fix.edits[].location`/`end_location` may now be
+   `null` instead of `""` and row 1, column 1. Any tooling that parses
+   `--output-format json` needs a null check.
+
+## Upgrade decision
+
+Two honest options; pick one and record it.
+
+- **Keep the old surface.** Pin the pre-0.16 defaults explicitly:
+
+  ```toml
+  [tool.ruff.lint]
+  select = ["E4", "E7", "E9", "F"]
+  ```
+
+  This is the documented escape hatch and is the right first move for a
+  large codebase mid-release.
+
+- **Adopt the new defaults.** Run `ruff check --fix`, then
+  `ruff check --statistics` on the remainder, and triage. Expect the
+  bulk of the noise from `I001`, `UP006`/`UP007`, `SIM`, `PYI`, and
+  `PLW`. Land the mechanical fixes first, then the judgement calls.
+
+Either way, run `ruff format` in the same commit — the 2026 style guide
+landed in 0.15.0 and will reflow lambdas, `except` tuples, and blank
+lines at the top of function bodies.
+
+## Suppression comments
+
+Ruff 0.16 supports four forms. `noqa` still works everywhere.
+
+```python
+import math  # ruff: ignore[F401]
+
+# ruff: ignore[E501]  covers the whole logical line below
+things = [
+    "really long string literal ...",
+]
+
+# ruff: file-ignore[F401] Re-exports are intentional here
+# ruff: disable[E741]
+l = 1
+# ruff: enable[E741]
+```
+
+- `ruff: ignore[...]` — trailing or own-line; own-line covers the entire
+  following *logical* line, which `noqa` cannot do.
+- `ruff: file-ignore[...]` — whole file, own-line, module scope.
+- `ruff: disable[...]` / `ruff: enable[...]` — block range, matching
+  codes and indentation. An unmatched `disable` is an implicit range and
+  raises `RUF104`.
+- `--add-ignore` inserts `ruff: ignore` comments the way `--add-noqa`
+  inserts `noqa`. In preview it writes human-readable rule names.
+
+Codes are stable; rule *names* in suppression comments and selectors are
+preview-only. See
+[suppression-comments.md](references/suppression-comments.md).
+
+## Settings added since 0.14
+
+| Setting                                  | Purpose                                          |
+| ---------------------------------------- | ------------------------------------------------ |
+| `extension`                              | Map extensions to `python`/`pyi`/`ipynb`/`markdown` |
+| `format.nested-string-quote-style`       | `alternating` (default) or `preferred` inside f-strings |
+| `lint.isort.import-heading`              | Section heading comments, per isort               |
+| `lint.flake8-tidy-imports.ban-lazy`      | Forbid `lazy import` for named modules (3.15+)    |
+| `lint.flake8-tidy-imports.require-lazy`  | Require `lazy import` where legal (3.15+)         |
+| `lint.pylint.max-statements-in-try`      | Threshold for `PLW0717`                           |
+| `lint.ruff.strictly-empty-init-modules`  | `RUF067` strictness                               |
+| `analyze.type-checking-imports`          | Include `TYPE_CHECKING` imports in the graph      |
+
+Details, defaults, and the CLI additions are in
+[settings-and-cli.md](references/settings-and-cli.md).
+
+## Red flags
+
+- A `pyproject.toml` upgraded to 0.16 with no `select` and no
+  discussion of the 413-rule default. Someone will be surprised.
+- `extend-select = ["ALL"]`-style configuration on 0.16. The defaults
+  already cover the useful ground; `ALL` now buys mostly conflict.
+- `# noqa` added in bulk to survive the upgrade. Use `--add-ignore`
+  once, with a follow-up issue, or fix the rule family properly.
+- CI parsing `--output-format json` without null handling.
+- A pre-commit config on 0.16 that expects Markdown to be untouched, or
+  one that expects Markdown to be formatted without `types_or` including
+  `markdown`.
+- Advice citing a rule as "preview" or "stable" without checking:
+  twelve rules stabilised in 0.16 and fifteen in 0.15. See
+  [rule-and-version-delta.md](references/rule-and-version-delta.md).