@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/python-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Should this config object be a dataclass or a pydantic model? It's loaded from a YAML file users edit.",
+    "Set up a new Python package with pyproject.toml, uv, ruff and mypy strict",
+    "Modernise this Python 3.7-era module: add type hints, replace the dict soup with proper types",
+    "My asyncio service freezes whenever it calls the old requests-based client, how should I restructure it?",
+    "Design an exception hierarchy for our Python billing library so callers can catch the right errors"
+  ],
+  "should_not_trigger": [
+    "Write pytest tests with fixtures and parametrize for the invoice module",
+    "Review this Python pull request for bugs before I merge it",
+    "mypy says 'Cannot find implementation or library stub for module named yaml', fix it",
+    "Add a FastAPI endpoint that creates a user and returns 201",
+    "Write idiomatic Go error handling for this HTTP handler"
+  ]
+}

package/skills/python-patterns/references/tooling.md

@@ -0,0 +1,101 @@
+# Python tooling reference
+
+Read this when setting up a new project or adding tooling to one that has none. If the project already configures a tool, keep its settings.
+
+## Package managers
+
+| Task | uv | poetry | pip + venv |
+|---|---|---|---|
+| Create env | `uv venv` (or implicit on `uv sync`) | `poetry install` | `python -m venv .venv` then activate |
+| Install from lock | `uv sync` | `poetry install` | `pip install -e ".[dev]"` or `pip install -r requirements.txt` |
+| Install exactly the lock, fail if stale (CI) | `uv sync --locked` | `poetry check --lock && poetry install` | `pip install -r requirements.txt` (pinned via pip-tools) |
+| Add runtime dep | `uv add httpx` | `poetry add httpx` | edit `[project.dependencies]`, reinstall |
+| Add dev dep | `uv add --dev pytest` | `poetry add --group dev pytest` | edit `[dependency-groups]` (install with `pip install --group dev` on a pip that supports it) or `[project.optional-dependencies].dev` / a requirements file |
+| Update lock | `uv lock` / `uv lock --upgrade-package httpx` | `poetry lock` / `poetry update httpx` | `pip-compile` (pip-tools) |
+| Run a tool | `uv run pytest` | `poetry run pytest` | activate `.venv`, then `pytest` |
+
+uv notes:
+- `uv sync` is exact by default: it removes packages not in the lockfile.
+- `--locked` errors if `uv.lock` is out of date; `--frozen` uses the lockfile without checking it.
+- Dev dependencies live in `[dependency-groups]` and the `dev` group is synced by default; skip it with `--no-dev`.
+
+## Minimal pyproject.toml
+
+```toml
+[project]
+name = "acme-billing"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.27"]
+
+[project.scripts]
+acme-billing = "acme_billing.cli:main"
+
+[dependency-groups]
+dev = ["pytest", "ruff", "mypy"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+```
+
+Use a `src/` layout (`src/acme_billing/__init__.py`) so tests import the installed package, not the working directory.
+
+## ruff
+
+```toml
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "S", "RUF"]
+```
+
+- `ruff check .` lints, `ruff check --fix .` applies safe fixes, `ruff format .` formats (replaces black). `ruff format` does not sort imports; with `I` selected, `ruff check --fix` does that (replaces isort).
+- `B` (bugbear) catches mutable defaults and loop-variable capture; `S` (bandit) catches `shell=True`, `eval` and hard-coded secrets; `UP` rewrites old syntax for `target-version`.
+- Rule selectors live under `[tool.ruff.lint]`, not top-level `[tool.ruff]`.
+
+## mypy
+
+```toml
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unreachable = true
+
+[[tool.mypy.overrides]]
+module = ["legacy.*"]
+ignore_errors = true
+```
+
+- Turn on `strict` for new code; on an existing codebase enable it per package with `overrides` instead of all at once.
+- Missing stubs: install `types-<pkg>` (for example `types-requests`), or set `ignore_missing_imports = true` in an override for that one module.
+- `mypy --install-types` can fetch missing stub packages, but review what it adds.
+
+## pyright
+
+```toml
+[tool.pyright]
+pythonVersion = "3.11"
+typeCheckingMode = "strict"
+venvPath = "."
+venv = ".venv"
+```
+
+- `typeCheckingMode` is `off`, `basic`, `standard` or `strict`.
+- If pyright can't resolve imports, it is almost always looking at the wrong interpreter: set `venvPath`/`venv` or run it inside the environment.
+
+## pre-commit
+
+```yaml
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: <pin a release tag>
+    hooks:
+      - id: ruff-check  # older ruff-pre-commit releases call it `ruff` (kept as a legacy alias)
+        args: [--fix]
+      - id: ruff-format
+```
+
+Pin `rev` to a real tag; check the ruff-pre-commit releases page for the current one.

package/skills/python-testing/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: python-testing
+description: Writes and repairs pytest suites for Python code using fixtures and conftest.py, parametrize, monkeypatch and unittest.mock, tmp_path, pytest-asyncio for coroutines, coverage with pytest-cov, and a procedure for diagnosing flaky or order-dependent tests. Use when adding tests to a Python project, converting unittest-style tests to pytest, mocking an external call in a Python test, or chasing a pytest test that passes locally but fails in CI.
+license: MIT
+compatibility: Any Agent Skills host. Needs python and pytest; async tests need pytest-asyncio (or anyio's pytest plugin), coverage needs pytest-cov.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "python"
+  kete-loom/owner: "Kete-org"
+---
+
+# Python testing with pytest
+
+Tests that are fast, deterministic and fail for one clear reason.
+
+## 0. Find the setup
+
+1. Find the test command: `[tool.pytest.ini_options]` in `pyproject.toml`, `pytest.ini`, `tox.ini`, `noxfile.py`, `Makefile`, CI config. Run through the env manager (`uv run pytest`, `poetry run pytest`, or an activated venv).
+2. Read the nearest `conftest.py` files. Reuse existing fixtures before writing new ones.
+3. Run the suite once and record the result. If it already fails, **stop and tell the user** which tests fail before you change anything.
+4. Note plugins in use (`pytest-asyncio`, `anyio`, `pytest-mock`, `pytest-django`, `pytest-xdist`, `hypothesis`). Follow their conventions; don't add a new plugin without asking.
+
+## 1. Writing a test
+
+- File `tests/test_<module>.py`, function `test_<behaviour>_<condition>`, e.g. `test_total_rejects_negative_quantity`.
+- One behaviour per test. Arrange, act, assert. Plain `assert`; pytest rewrites it to show values.
+- Test through the public API. Don't assert on private helpers or call counts unless the call is the behaviour.
+- Errors: `with pytest.raises(ValueError, match="negative"):`. Keep the `with` block to the single call that should raise.
+- Floats: `assert x == pytest.approx(0.3)`.
+- Warnings: `with pytest.warns(DeprecationWarning):`.
+
+## 2. Fixtures
+
+- A fixture provides one thing. Name it for what it gives (`user`, `db_session`), not what it does.
+- Cleanup goes after `yield` in the fixture:
+
+  ```python
+  @pytest.fixture
+  def client():
+      c = make_client()
+      yield c
+      c.close()
+  ```
+
+- Scope: default `function`. Widen to `module` or `session` only for expensive, read-only resources; a shared mutable fixture causes order-dependent failures.
+- Share fixtures through `conftest.py` in the closest directory that needs them, not one giant root file.
+- Factories: when tests need several variants, return a function (`make_user(role="admin")`) rather than writing ten fixtures.
+- Avoid `autouse=True` except for true global guards (blocking network, resetting a singleton).
+
+## 3. Parametrize
+
+```python
+@pytest.mark.parametrize(
+    ("raw", "expected"),
+    [("1h", 3600), ("90s", 90), ("0m", 0)],
+    ids=["hours", "seconds", "zero"],
+)
+def test_parse_duration(raw, expected):
+    assert parse_duration(raw) == expected
+```
+
+- Use it for the same behaviour over many inputs; use separate tests when the assertions differ.
+- Give `ids` when values are long or unreadable.
+- Mark one known case with `pytest.param(..., marks=pytest.mark.xfail(reason="#123"))` rather than deleting it.
+
+## 4. Patching and mocking
+
+Decision rule: patch only boundaries you don't own or can't run fast (network, clock, randomness, subprocess, third-party SDKs). Never mock the unit under test.
+
+- Environment and attributes: `monkeypatch.setenv("API_URL", "http://test")`, `monkeypatch.setattr(module, "fetch", fake)`, `monkeypatch.delenv(..., raising=False)`. Undone automatically.
+- **Patch where the name is looked up, not where it is defined.** If `app/billing.py` does `from app.http import post`, patch `app.billing.post`.
+- Use `unittest.mock.create_autospec(Real)` or `patch(..., autospec=True)` so the mock fails on wrong signatures.
+- Coroutines: `AsyncMock` (used automatically by `patch` when the target is `async def`).
+- Prefer a small fake class or an in-memory implementation over a deep chain of `MagicMock().a.b.return_value`.
+- HTTP: use the project's existing tool (`respx` for httpx, `responses` for requests) instead of patching internals.
+- Time: inject a clock, or use the project's freezer (`time-machine`, `freezegun`). Never `sleep` in a test to wait for time to pass.
+
+More mocking patterns and pitfalls: `references/mocking.md`.
+
+## 5. Files and output
+
+- `tmp_path` gives a fresh `pathlib.Path` per test; `tmp_path_factory` for session scope. Never write into the repo or `/tmp` directly.
+- `capsys` / `capfd` for stdout and stderr, `caplog` for log records (`caplog.set_level(logging.INFO)` first).
+- `monkeypatch.chdir(tmp_path)` when code uses relative paths.
+
+## 6. Async code
+
+- pytest-asyncio: mark tests `@pytest.mark.asyncio`, or set `asyncio_mode = "auto"` in `[tool.pytest.ini_options]` so every `async def` test runs. The default mode is `strict`; in strict mode async fixtures need `@pytest_asyncio.fixture`. An unmarked `async def` test never runs: older pytest skips it with a warning, pytest 8.4+ fails it.
+- If the project uses anyio (common with FastAPI/Starlette/httpx), use `@pytest.mark.anyio` and its `anyio_backend` fixture instead. Don't install both styles in one suite.
+- Await everything. A test that calls a coroutine without `await` passes without running it; pytest emits a "coroutine was never awaited" warning. Treat that warning as a failure.
+- Bound waits with `asyncio.timeout(...)` / `asyncio.wait_for(...)` so a hung test fails rather than blocks CI.
+- Check the installed pytest-asyncio version's docs for event-loop scope options before changing loop scope; the API changed across releases.
+
+## 7. Coverage
+
+- `pytest --cov=<package> --cov-report=term-missing` (pytest-cov). Use `--cov-branch` to see untaken branches.
+- Read the missing lines; add tests for behaviour that matters (error paths, boundaries), not to hit a number.
+- Respect `fail_under` in `[tool.coverage.report]` if set. Never lower it without asking.
+
+## 8. Flaky tests
+
+Work through in order, and stop at the first cause you can prove:
+
+1. Reproduce: rerun the single test many times (`pytest path::test -x --count 50` with pytest-repeat if installed, or a shell loop).
+2. Order dependence: run it alone, then with the full file, then with pytest-randomly's seed from the failing run (`--randomly-seed=<seed>`), or disable shuffling with `-p no:randomly` to compare. Passing alone but failing in the suite means shared state: a module-level cache, a wide-scope mutable fixture, an unreset singleton, leaked env vars.
+3. Parallelism: compare with and without `-n auto` (pytest-xdist). Shared files, ports or DB rows break under xdist; use `tmp_path` and per-worker names (`worker_id` fixture).
+4. Time and randomness: dates near midnight or month end, timezones, unseeded `random`, set or dict ordering assumptions.
+5. Async and threads: missing `await`, sleeps used as synchronisation, tasks still running after the test ends.
+6. Real network or external services.
+
+Fix the cause. Never "fix" flakiness by adding retries, `sleep`, or `@pytest.mark.skip` without the user agreeing; if you must quarantine, use `xfail(strict=False, reason=...)` with an issue link.
+
+## Rules
+
+- Never delete, skip or weaken an existing test to get green. Explain to the user if you think a test is wrong.
+- No real network, no real clock dependence, no shared state between tests.
+- Run the single new test first, then its file, then the whole suite.
+- After three focused attempts at a failing test, stop and report what you tried.
+
+For test-first workflow (red, green, refactor), use the `tdd-workflow` skill. For browser-level tests, use `e2e-testing-playwright`.
+
+## Report back
+
+Tests added or changed (names), the exact command run, pass/fail counts, coverage change if measured, and for flaky tests the proven root cause.

package/skills/python-testing/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Write pytest tests for the parse_invoice function, use parametrize for the edge cases",
+    "How do I mock the httpx call inside my service when testing it with pytest?",
+    "test_sync_orders passes on my machine but fails randomly in CI with pytest-xdist",
+    "Add tests for this async def fetch_rates coroutine, we use pytest-asyncio",
+    "Convert these unittest.TestCase classes to plain pytest functions with fixtures"
+  ],
+  "should_not_trigger": [
+    "Should I use a dataclass or pydantic for this Python settings object?",
+    "Review my Python diff for mutable default arguments and swallowed exceptions",
+    "pip install fails with ResolutionImpossible on our Python project, sort it out",
+    "Write Jest tests for this TypeScript reducer",
+    "Write a Playwright end-to-end test for the login page"
+  ]
+}

package/skills/python-testing/references/mocking.md

@@ -0,0 +1,71 @@
+# Mocking and patching in pytest
+
+Read this when a test needs to replace a dependency and the short rules in `SKILL.md` aren't enough.
+
+## Where to patch
+
+```python
+# app/http.py
+def post(url, data): ...
+
+# app/billing.py
+from app.http import post
+def charge(amount): return post("/charge", {"amount": amount})
+```
+
+- `patch("app.billing.post")` works: `charge` looks up `post` in `app.billing`.
+- `patch("app.http.post")` does nothing for `charge`, because `app.billing` already holds its own reference.
+- If the module does `import app.http` and calls `app.http.post(...)`, then patch `app.http.post`.
+
+## monkeypatch vs unittest.mock
+
+| Need | Use |
+|---|---|
+| Set or remove an env var | `monkeypatch.setenv` / `monkeypatch.delenv` |
+| Replace a function with a simple fake | `monkeypatch.setattr("app.billing.post", fake_post)` |
+| Assert how a boundary was called | `mocker.patch(...)` (pytest-mock) or `unittest.mock.patch(...)` |
+| Fake an object with a real class's signature | `create_autospec(RealClass, instance=True)` |
+| Fake an `async def` | `AsyncMock`, or `patch(..., autospec=True)` on the coroutine function |
+
+Both monkeypatch and `patch` used as a context manager or decorator undo themselves. A `patch(...).start()` without `.stop()` leaks into later tests; use `mocker` (pytest-mock) or a fixture with `yield` instead.
+
+## Asserting calls
+
+```python
+from unittest.mock import patch
+
+def test_charge_posts_amount():
+    with patch("app.billing.post", autospec=True) as post:
+        post.return_value = {"ok": True}
+        charge(500)
+    post.assert_called_once_with("/charge", {"amount": 500})
+```
+
+- A plain `Mock` raises `AttributeError` for misspelled names starting with `assert` / `assret` / `asert` / `aseert` / `assrt`. On Python before 3.12, `post.called_once_with(...)` (no `assert_`) just creates a child mock and the test passes without checking anything; 3.12 also rejects that. Autospecced mocks reject unknown attributes on every version, so prefer `autospec=True`.
+- `side_effect=Exception("boom")` to test error paths; `side_effect=[1, 2, StopIteration]` for sequences.
+
+## Fakes over mocks
+
+For repositories, caches and queues, an in-memory fake is clearer than a mock:
+
+```python
+class FakeUserRepo:
+    def __init__(self): self.users = {}
+    def get(self, uid): return self.users.get(uid)
+    def save(self, user): self.users[user.id] = user
+```
+
+Inject it through the constructor or a fixture. The test then asserts on state (`repo.users`) instead of call sequences.
+
+## HTTP
+
+- httpx: `respx` (`respx.mock` fixture or decorator) or `httpx.MockTransport`.
+- requests: `responses` (`@responses.activate`) or `requests-mock`.
+- Block accidental real calls in CI: the project's choice, for example pytest-socket's `--disable-socket`.
+
+## Common pitfalls
+
+- Patching `datetime.datetime.now` directly fails (built-in type). Inject a clock or use `time-machine` / `freezegun`.
+- `MagicMock` is truthy and returns more mocks for any attribute, so code under test can "succeed" on nonsense. Autospec, or use a fake.
+- Mocks in a `session`-scoped fixture are shared by every test; keep mocks `function`-scoped.
+- Over-mocking: if a test patches more than two or three things, test a smaller unit or use a fake.

package/skills/pytorch-patterns/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: pytorch-patterns
+description: Writes and fixes PyTorch training code, covering nn.Module and training loop structure, device and dtype placement, DataLoader setup, torch.amp mixed precision, checkpoint save and resume, seeding for reproducibility, and tracking down NaN losses and tensor shape errors. Use when building or debugging a PyTorch model, a training or evaluation loop, or a checkpoint that will not load.
+license: MIT
+compatibility: Any Agent Skills host. Needs Python and PyTorch 2.x; GPU sections assume CUDA but the rules hold for CPU and MPS.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: ai
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "python"
+  kete-loom/owner: "Kete-org"
+---
+
+# PyTorch patterns
+
+Write training code that runs the same way twice, fails loudly on bad shapes, and can resume after a crash. For how to design the experiment itself (splits, baselines, metrics), use the `ml-experiment-workflow` skill instead.
+
+## 0. Before you write code
+
+1. Find the PyTorch version (`python -c "import torch; print(torch.__version__)"`) and the target device. Write for that version.
+2. Find the existing training entry point, config and data code. Extend them; do not start a second training script.
+3. **Stop and ask the user** if the target device, the metric being optimised, or the expected input shape is unclear.
+
+## 1. Structure
+
+- One `nn.Module` per model. `__init__` builds layers; `forward` only computes. No data loading, logging or `.to(device)` inside `forward`.
+- Keep three separate functions: `train_one_epoch(model, loader, optimizer, ...)`, `evaluate(model, loader)`, and a `main()` that wires config, data, model and checkpoints.
+- Put hyperparameters in one config object (dataclass, YAML, argparse). Save it next to every checkpoint.
+- Register non-trainable tensors with `self.register_buffer(...)` so they move with `.to()` and land in `state_dict`. Store sub-modules in `nn.ModuleList`/`nn.ModuleDict`, never a plain list or dict, or their parameters are invisible to the optimizer.
+
+## 2. The training step
+
+```python
+use_amp = device.type == "cuda"
+scaler = torch.amp.GradScaler("cuda", enabled=use_amp and amp_dtype == torch.float16)
+model.train()
+for x, y in loader:
+    x, y = x.to(device, non_blocking=True), y.to(device, non_blocking=True)
+    optimizer.zero_grad(set_to_none=True)
+    with torch.amp.autocast(device_type=device.type, dtype=amp_dtype, enabled=use_amp):
+        loss = criterion(model(x), y)
+    scaler.scale(loss).backward()
+    scaler.unscale_(optimizer)                      # only if clipping
+    torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm)
+    scaler.step(optimizer)
+    scaler.update()
+    scheduler.step()                                # per-step schedulers only
+```
+
+Evaluation:
+
+```python
+model.eval()
+with torch.inference_mode():
+    for x, y in loader: ...
+```
+
+Rules:
+
+- Always pair `model.train()` / `model.eval()`. Forgetting `eval()` leaves dropout on and batch norm updating running stats.
+- Log `loss.item()` (or `.detach()`) not `loss`, or you keep the whole graph alive and leak memory.
+- Call `scheduler.step()` after `optimizer.step()`. Decide once whether the scheduler steps per batch or per epoch and match the schedule's length to that.
+- For gradient accumulation, divide the loss by the number of accumulation steps and only step/zero the optimizer every N batches.
+
+## 3. Device and dtype
+
+- Pick the device once: `device = torch.device("cuda" if torch.cuda.is_available() else "cpu")` (add `"mps"` if the project targets Apple silicon). Pass it down; do not call `.cuda()` in scattered places.
+- Move the model to the device **before** creating the optimizer.
+- Create new tensors on the right device and dtype: `torch.zeros(n, device=x.device, dtype=x.dtype)`, not `torch.zeros(n).to(...)` later.
+- Classification targets for `CrossEntropyLoss` are `long` class indices of shape `(N,)` (or probabilities of shape `(N, C)`); logits are raw, no softmax first. `BCEWithLogitsLoss` takes float targets the same shape as the logits.
+
+## 4. Data loading
+
+- `Dataset.__getitem__` returns one sample; batching is the `DataLoader`'s job.
+- Training loader: `shuffle=True`, `num_workers>0`, `pin_memory=True` on CUDA, `persistent_workers=True` when `num_workers>0`, `drop_last=True` if batch norm sees tiny last batches.
+- Eval loader: `shuffle=False`, `drop_last=False`, so every sample is scored once.
+- Fit normalisation statistics, vocabularies and tokenizers on the training split only.
+- First debug step for a slow loop: time an epoch with the model step removed. If the loader alone is slow, fix the loader before touching the model.
+
+## 5. Mixed precision
+
+- Use the device-generic API: `torch.amp.autocast("cuda", dtype=...)` and `torch.amp.GradScaler("cuda")`. `torch.cuda.amp.*` is deprecated.
+- `float16` needs a `GradScaler`. `bfloat16` (Ampere-class GPUs and newer, and CPU) has float32's range and is normally run without one; pass `enabled=False` to the scaler so the loop stays the same.
+- Wrap only the forward pass and loss in `autocast`. Run `backward()` outside it.
+- Use built-in ops for precision-sensitive maths (`log_softmax`, `cross_entropy`, `mse_loss`, `binary_cross_entropy_with_logits`): autocast runs these in float32. Hand-written `exp`/`log`/sum chains get no such protection.
+
+## 6. Checkpoints
+
+Save everything needed to resume, not just the weights:
+
+```python
+torch.save({
+    "model": model.state_dict(), "optimizer": optimizer.state_dict(),
+    "scheduler": scheduler.state_dict(), "scaler": scaler.state_dict(),
+    "epoch": epoch, "step": step, "config": asdict(cfg),
+    "rng": {"torch": torch.get_rng_state(), "cuda": torch.cuda.get_rng_state_all()},
+}, tmp_path)
+os.replace(tmp_path, path)      # atomic: a crash never leaves a half-written file
+```
+
+- Load with `torch.load(path, map_location=device)`. Since PyTorch 2.6 the default is `weights_only=True`, so a checkpoint holding custom objects fails to load. Store plain types (dicts, lists, tensors, numbers) instead, or allowlist the class with `torch.serialization.add_safe_globals([...])`. Only pass `weights_only=False` for files you created yourself.
+- If the model was wrapped (`DistributedDataParallel`, `torch.compile`), save the unwrapped module's `state_dict` (`model.module` or `model._orig_mod`) so keys have no `module.` / `_orig_mod.` prefix.
+- Keep the best checkpoint (by validation metric) separate from the latest one.
+
+## 7. Reproducibility
+
+```python
+def seed_everything(seed: int):
+    random.seed(seed); np.random.seed(seed); torch.manual_seed(seed)  # seeds all devices
+```
+
+- DataLoader workers: pass `generator=torch.Generator().manual_seed(seed)` and a `worker_init_fn` that seeds NumPy and `random` from `torch.initial_seed() % 2**32`.
+- For bit-exact runs: `torch.use_deterministic_algorithms(True)`, `torch.backends.cudnn.benchmark = False`, and set the environment variable `CUBLAS_WORKSPACE_CONFIG=:4096:8` before CUDA starts. This costs speed; turn it on for debugging and comparisons, not by default.
+- Log the seed, the git commit and the library versions with each run.
+
+## 8. Debugging
+
+Read `references/debugging.md` for the full NaN and shape checklists. The short version:
+
+- **Shape errors**: print `x.shape` at each layer boundary for one batch, or assert expected shapes (`assert x.shape[1:] == (3, 224, 224), x.shape`). Watch for silent broadcasting: `(N,)` minus `(N, 1)` gives `(N, N)` without an error.
+- **NaN or inf loss**: check the input batch first (`torch.isfinite(x).all()`), then the learning rate, then the loss (log of zero, division by zero), then fp16 overflow. Turn on `torch.autograd.set_detect_anomaly(True)` for one short run to find the op that produced it; it is slow, never leave it on.
+- **Loss does not go down**: overfit a single batch of 2 to 32 samples. If the model can't drive loss near zero on one batch, the bug is in the model, loss or labels, not in the hyperparameters.
+
+## Never
+
+- Never call `model(x)` for evaluation without `model.eval()` and `inference_mode()`/`no_grad()`.
+- Never apply softmax before `CrossEntropyLoss` or sigmoid before `BCEWithLogitsLoss`.
+- Never `torch.load` an untrusted file with `weights_only=False`.
+- Never compare runs that used different seeds, data splits or eval code without saying so.
+
+## Report
+
+When you change training code, end with:
+
+```
+Changed: <files and what changed>
+Verified: <command run, e.g. one-batch overfit or 1-epoch smoke run, and its result>
+Not checked: <e.g. multi-GPU, full-length run>
+```

package/skills/pytorch-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "My PyTorch training loss turns into NaN after about 300 steps, help me find out why",
+    "Add bf16 mixed precision and gradient clipping to this torch training loop",
+    "RuntimeError: mat1 and mat2 shapes cannot be multiplied (64x2048 and 512x10) in my nn.Module",
+    "Make my PyTorch checkpoints resumable, including optimizer and scheduler state",
+    "Two runs of the same torch script with seed 42 give different accuracy, make it deterministic"
+  ],
+  "should_not_trigger": [
+    "Set up a proper train/validation/test split and a baseline before we try the transformer",
+    "Review this training notebook for data leakage and wrong metrics before we publish the results",
+    "Write pytest unit tests for the Python utility module that parses CSV files",
+    "Build a retrieval pipeline that chunks our docs and stores embeddings in pgvector",
+    "Write an eval harness that scores our chatbot's answers against a golden set"
+  ]
+}

package/skills/pytorch-patterns/references/debugging.md

@@ -0,0 +1,39 @@
+# PyTorch debugging checklists
+
+Read this when a run produces NaN/inf, a shape error, or a loss that will not move.
+
+## NaN or inf loss
+
+Work top to bottom and stop at the first thing that is wrong.
+
+1. **Inputs.** For the failing batch: `torch.isfinite(x).all()`, `x.min()`, `x.max()`. Missing values in tabular data, empty images and divide-by-zero in preprocessing are the most common cause.
+2. **Labels.** Class indices must be in `[0, num_classes)`. An out-of-range label on CUDA often shows as a device-side assert; rerun on CPU, or with `CUDA_LAUNCH_BLOCKING=1`, to get a readable traceback.
+3. **Learning rate.** Drop it by 10x. If the NaN disappears, add warmup or gradient clipping (`clip_grad_norm_`) rather than keeping the smaller rate blindly.
+4. **Loss maths.** Replace hand-written `log(softmax(x))` with `log_softmax` or the built-in loss; add `eps` to denominators and to `sqrt`/`log` arguments.
+5. **Mixed precision.** Rerun with autocast disabled. If fp32 is stable, switch to bfloat16 or check that the `GradScaler` is used and that its scale is not collapsing (`scaler.get_scale()`).
+6. **Find the op.** Wrap one short run in `torch.autograd.set_detect_anomaly(True)`; the error names the backward op that produced the NaN. Or register forward hooks that assert `torch.isfinite(output).all()` per module.
+
+## Shape errors
+
+1. Print the shapes at the error line, and the shapes of the inputs to the module that raised it.
+2. Check the layer's expected layout: `Conv2d` wants `(N, C, H, W)`, `nn.Linear` acts on the last dimension, `nn.LSTM`/`nn.MultiheadAttention` default to `batch_first=False` (`(T, N, E)`).
+3. A `Linear` input-size mismatch after a conv stack: compute it from a dummy forward (`model.features(torch.zeros(1, *input_shape)).shape`) or use `nn.LazyLinear`.
+4. **Silent broadcasting.** These run without error and give wrong numbers:
+   - `pred` of shape `(N, 1)` with `target` of shape `(N,)` in `MSELoss` or arithmetic: result is `(N, N)`. PyTorch warns for `MSELoss`; it does not warn for plain arithmetic.
+   - `x.sum()` or `x.mean()` without `dim=` collapsing the batch.
+   - `view` after `permute`/`transpose` on a non-contiguous tensor raises; `reshape` silently copies. Neither is wrong, but a `view(N, -1)` over the wrong axis order scrambles data. Check with a small hand-made tensor.
+5. Add shape asserts at module boundaries in the fixed code, so the next regression fails loudly.
+
+## Loss does not decrease
+
+1. Overfit one small batch for a few hundred steps. Failure means a bug, not tuning.
+2. Check the optimizer sees the parameters: `sum(p.numel() for g in optimizer.param_groups for p in g["params"])` equals the model's trainable count.
+3. Check gradients flow: after `backward()`, every trainable parameter has a non-None, non-zero `.grad`. A `None` grad usually means a `.detach()`, `.item()`, `torch.no_grad()` or a NumPy round-trip broke the graph.
+4. Check `optimizer.zero_grad()` is called each step, and that `requires_grad` is not off on layers you meant to train.
+5. Check the labels line up with the inputs (shuffle applied to one but not the other, off-by-one in a sequence target).
+
+## Out of memory
+
+1. Log `torch.cuda.max_memory_allocated()` per step.
+2. Look for tensors kept across steps: accumulating `loss` instead of `loss.item()`, appending outputs to a list during training.
+3. Then reduce batch size with gradient accumulation, enable mixed precision, or use activation checkpointing (`torch.utils.checkpoint.checkpoint`).

package/skills/quarkus-patterns/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: quarkus-patterns
+description: Quarkus service conventions for ArC CDI beans, Quarkus REST (formerly RESTEasy Reactive) endpoints, Hibernate ORM with Panache, @ConfigMapping and %dev/%test/%prod profiles, Dev Services containers, GraalVM native-image limits, and @QuarkusTest or @QuarkusIntegrationTest suites. Use when writing or debugging a Quarkus application, choosing blocking versus reactive endpoints, configuring a Quarkus extension, or getting a Quarkus build to work as a native executable.
+license: MIT
+compatibility: Any Agent Skills host. Needs a JDK and the project's Maven or Gradle wrapper (or the Quarkus CLI). Dev Services and container tests need Docker or Podman. Native builds need GraalVM/Mandrel or a container runtime. Written for Quarkus 3.x.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "java"
+  kete-loom/owner: "Kete-org"
+---
+
+# Quarkus patterns
+
+Quarkus moves work to build time. Most surprises come from forgetting that: beans, config and reflection are resolved when the app is built, not when it starts. Write code that the build can see.
+
+## 0. Before you start
+
+1. Read the Quarkus version and extensions from `pom.xml` (`quarkus-bom`) or `build.gradle(.kts)`. Note whether the project uses `quarkus-rest` (Quarkus REST) or the legacy `quarkus-resteasy` (Classic). **Never mix** `quarkus-rest*` and `quarkus-resteasy*` extensions; that causes duplicate-implementation startup errors.
+2. Find the build and test command: `./mvnw verify`, `./gradlew build`, or `quarkus build`. Run tests once and record the result; stop and tell the user if they already fail.
+3. Add extensions with `./mvnw quarkus:add-extension -Dextensions="..."` or `quarkus ext add ...`, not by guessing artifact ids.
+
+## 1. CDI (ArC)
+
+- Default to `@ApplicationScoped` for services. Use `@Singleton` only when you need no client proxy, and `@RequestScoped` for per-request state.
+- Use constructor injection; a single constructor needs no `@Inject`. Package-private field injection also works without reflection, but private field injection forces reflection; avoid it.
+- ArC discovers beans at build time. A class in a dependency jar without a Jandex index is invisible; add the index (`jandex-maven-plugin`) or `quarkus.index-dependency.*` config.
+- Unused beans are removed at build time. If a bean is only looked up programmatically, mark it `@Unremovable`.
+- Produce third-party objects with `@Produces` methods in an `@ApplicationScoped` class.
+- Use `@Startup` or `void onStart(@Observes StartupEvent ev)` for startup work; keep it fast.
+
+## 2. REST endpoints (Quarkus REST)
+
+- Resources use Jakarta REST annotations: `@Path`, `@GET`, `@POST`, `@Produces`, `@Consumes`. Add `quarkus-rest-jackson` (or `-jsonb`) for JSON.
+- **Threading rule**: a method returning a plain type or `Response` runs on a worker thread and may block. A method returning `Uni` or `Multi` runs on the event loop and **must never block** (no JDBC, no `Thread.sleep`, no blocking HTTP). Use `@Blocking` or `@NonBlocking` to override when needed. Blocking on the event loop logs a "blocked thread" warning; treat it as a bug.
+- Pick one model per service. Hibernate ORM (blocking) with plain return types is the simple default; use Hibernate Reactive with `Uni` only when the project already does.
+- Return DTO records, not entities. Validate input with `quarkus-hibernate-validator` and `@Valid`.
+- Map exceptions to responses with `@ServerExceptionMapper` methods (or an `ExceptionMapper`). Never leak stack traces.
+- Call other services with the REST client: an interface annotated `@RegisterRestClient(configKey = "orders-api")`, injected with `@RestClient`, base URL in `quarkus.rest-client.orders-api.url`.
+
+## 3. Panache
+
+- Choose one style per project and keep it:
+  - **Active record**: `class Order extends PanacheEntity` (gives a `Long id`), static finders like `Order.find("status", s).list()`.
+  - **Repository**: `class OrderRepository implements PanacheRepository<Order>`, injected into services. Easier to mock.
+- Panache entities use public fields; Quarkus rewrites access into getters and setters at build time.
+- Writes need a transaction: annotate the service or resource method with `@Transactional` (`jakarta.transaction`). Reads outside a transaction work but lazy loading after the method returns fails.
+- Page large queries: `find(...).page(Page.of(index, size))`. Never `listAll()` on a table that grows.
+- The fetch, N+1 and locking rules in the `jpa-hibernate` skill apply here too.
+
+## 4. Configuration and profiles
+
+- Group related settings in an interface with `@ConfigMapping(prefix = "payments")`; use `@ConfigProperty(name = "...")` only for one-off values. Missing required values fail startup, which is what you want.
+- Profiles prefix keys: `%dev.`, `%test.`, `%prod.` in `application.properties`, or `application-{profile}.properties`. A custom profile is set with `quarkus.profile`.
+- Know the two kinds of config: **build-time** properties (marked with a lock in the config reference, such as `quarkus.datasource.db-kind`) are fixed when you build and can't be changed by environment at runtime. Runtime properties can be set by env vars (`QUARKUS_DATASOURCE_JDBC_URL`).
+- Secrets come from environment variables or a config source like Vault or Kubernetes secrets, never committed properties.
+
+## 5. Dev Services
+
+- With an extension such as `quarkus-jdbc-postgresql` and **no** URL configured, dev and test mode start a container automatically. Don't configure `%dev`/`%test` datasource URLs unless you want to opt out.
+- Set `quarkus.datasource.devservices.image-name` to match the production database version.
+- Dev Services never runs in prod. Production config must set real URLs and credentials.
+- Use `quarkus dev` (or `./mvnw quarkus:dev`) for live reload and the Dev UI at `/q/dev-ui`.
+
+## 6. Native image constraints
+
+Build with `./mvnw install -Dnative`, `./gradlew build -Dquarkus.native.enabled=true`, or `quarkus build --native`. Add `-Dquarkus.native.container-build=true` when no local GraalVM is installed. Native code is closed-world:
+
+- Reflection, dynamic proxies and resources must be known at build time. Register classes used only reflectively (for example DTOs serialised by a library Quarkus doesn't know) with `@RegisterForReflection`; include resource files with `quarkus.native.resources.includes`.
+- Static initialisers run at build time by default. Code that reads the clock, randomness, env vars or opens connections in a static block must be moved to runtime init.
+- Prefer Quarkus extensions over plain libraries; extensions carry the native configuration.
+- Run `@QuarkusIntegrationTest` against the native build. Passing JVM tests prove nothing about native.
+- **Stop and ask the user** before switching a project to native: builds are slow and memory-hungry, and some libraries won't work.
+
+## 7. Testing
+
+- `@QuarkusTest` starts the app once per test run in JVM mode, with Dev Services, on the `test` profile. Use REST Assured (`given().when().get("/orders/1").then().statusCode(200)`).
+- `@QuarkusIntegrationTest` runs the packaged artifact (jar, native binary or container) as a black box; it can't inject beans.
+- Mock beans with `@InjectMock` (needs `quarkus-junit5-mockito`); it works for normal-scoped beans like `@ApplicationScoped`; a `@Singleton` bean can only be mocked with `@MockitoConfig(convertScopes = true)`, which changes its scope in the test, so prefer making the bean `@ApplicationScoped`. Beans used during startup are not mocked. Use `@TestProfile` for different config; each profile restarts the app, so use few.
+- Use `@TestTransaction` to roll back database changes after each test.
+- Use a test resource (`@QuarkusTestResource`, or `@WithTestResource` to group tests by resource) only for dependencies Dev Services can't provide.
+
+## Never
+
+- Blocking calls inside a `Uni`/`Multi` method or on the event loop.
+- `quarkus-rest` and `quarkus-resteasy` in the same build.
+- Private field injection or reflection-heavy libraries in a native build without registering them.
+- Hard-coded datasource URLs in `%dev`/`%test` that disable Dev Services by accident.
+
+## Before you finish
+
+Run the tests (and `-Dnative` integration tests if the project ships native). Report: extensions added, config keys and which profile they apply to, threading model of new endpoints, tests added, and the final test counts.

package/skills/quarkus-patterns/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Build a Quarkus REST endpoint backed by Panache and make it compile to a native image",
+    "Quarkus logs 'You have attempted to perform a blocking operation on an IO thread' in my Uni endpoint",
+    "How do Dev Services in Quarkus start Postgres for tests, and why did it stop after I set a JDBC url?",
+    "Set up %dev and %prod profiles with @ConfigMapping in our Quarkus microservice",
+    "My Quarkus native executable fails at runtime with a ClassNotFoundException for a Jackson DTO",
+    "Use @InjectMock in a @QuarkusTest to replace the payment client bean"
+  ],
+  "should_not_trigger": [
+    "Add a new REST endpoint to our Spring Boot order service with request validation and proper 404 responses",
+    "Write a Ktor route for uploading files with coroutines",
+    "Add a Flyway migration that adds a NOT NULL column to the orders table without downtime",
+    "Write the Dockerfile and Kubernetes deployment for our Java service",
+    "Explain idiomatic Java records and sealed interfaces for our domain model",
+    "Our Gradle build fails with a dependency resolution conflict in the Java module"
+  ]
+}