@mrciphersmith/keryx 0.2.164 → 0.3.1

package/src/gdskills/bundled/stacks/python/skills/python-code-review/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: python-code-review
+description: "Use when reviewing Python changes for correctness and safety risks -- checks mutable default arguments, broad except clauses, resource leaks missing a with block, blocking calls inside async functions, typing holes (Any, missing Optional), N+1/ORM query misuse, and security sinks. Read-only: reports findings, does not edit code."
+triggers:
+  - "review this python diff"
+  - "check this python pr for bugs"
+  - "review python code changes"
+  - "audit this python module"
+  - "check for python security issues"
+  - "review this async python code"
+metadata:
+  origin: authored
+  category: review
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Python code review
+
+Review a set of Python changes for correctness, resource-safety, typing, and
+security risk. Read-only: this skill reports findings, it never edits code.
+Scoped to Python-specific defects; for generic architecture/style review use
+the catalog's `review-*` skills, for a language-agnostic security sweep use
+`review-security-code`, for fixing what this skill finds use
+`python-build-fix` (checker failures) or hand the report to the author.
+
+## Workflow
+
+### Step 1: Scope the review
+
+1. Identify the changed Python files (`git diff` against the review base,
+   or the files the requester names).
+2. Read `pyproject.toml` for the project's configured `ruff`/`mypy`/
+   `pyright` rules — a finding this skill would raise that the project's
+   own linter already enforces and passes on is lower priority than one the
+   linter cannot catch (logic, resource, or security issues).
+3. Read enough of the surrounding module (call sites, class definition) to
+   judge whether a flagged pattern is actually a bug in context, not just a
+   pattern match.
+
+### Step 2: Check each changed file against these categories
+
+**Mutable defaults and shared state**
+- `def f(items=[])`/`def f(config={})` — a mutable default is shared and
+  mutated across every call that omits the argument.
+- A module-level or class-level mutable used as implicit shared state
+  across requests/calls without synchronization.
+
+**Exception handling**
+- Bare `except:` or `except Exception:` that swallows an error the caller
+  needed to see, especially one that also catches
+  `asyncio.CancelledError`/`KeyboardInterrupt`/`SystemExit`.
+- A re-raise inside an `except` block written as bare `raise NewError(...)`
+  with no `from exc`/`from None`. Python keeps the original exception either
+  way through implicit chaining (`__context__`, printed as "During handling
+  of the above exception..."), so this is not a lost traceback — it's a
+  missing statement of intent: `from exc` says the new exception was caused
+  by the original, `from None` says the original is deliberately suppressed
+  and shouldn't be shown.
+- An `except` block that logs and continues where the correct behavior was
+  to propagate.
+
+**Resource management**
+- A file, socket, DB connection, lock, or temp resource opened without
+  `with`/`async with`, or closed only on the happy path (no `finally`/
+  context manager covering the exception path).
+- A context manager whose `__exit__`/`finally` doesn't actually run cleanup
+  when the body raises.
+
+**Async correctness**
+- A blocking call (`requests.get`, `time.sleep`, synchronous file I/O, a
+  CPU-bound loop) directly inside an `async def` instead of the async
+  client, `asyncio.sleep`, or `asyncio.to_thread`.
+- A coroutine created but never awaited (`asyncio.create_task` result
+  discarded with no reference kept, or a bare `coro()` call with no
+  `await`).
+- `asyncio.gather`/manual task tracking where a `TaskGroup` would give
+  correct sibling-cancellation semantics, if the project targets 3.11+.
+
+**Typing**
+- A new/touched public function with no type hints, or a hint that is
+  `Any` where a `Protocol`/union/`TypeVar` would express the real
+  constraint.
+- A parameter or return that can be `None` at some call site but is typed
+  without `Optional`/`| None`.
+- A type: ignore/noqa added to silence a real typing/lint issue rather than
+  fixing it.
+
+**Data access**
+- A loop that issues one query per iteration (N+1) where a single
+  batched/joined query or `select_related`/`prefetch_related` (Django) or
+  equivalent eager-load would do.
+- An ORM query built by interpolating a value into a raw SQL string instead
+  of using parameter binding or the ORM's query builder.
+
+**Security** (full list: `rules/security.mdc`)
+- `subprocess` with `shell=True` or a string command.
+- `eval`/`exec` on anything that could carry untrusted input.
+- `pickle.load`/`yaml.load` (not `safe_load`) on data not fully controlled
+  by the project.
+- SQL built by string interpolation instead of parameters.
+- A network call with no `timeout`, or `verify=False`.
+- A hard-coded secret, or a token generated with `random` instead of
+  `secrets`.
+
+### Step 3: Report
+
+For each finding: file:line, category, what's wrong, and the safe
+alternative (cite the exact API/pattern, e.g. "use `secrets.token_urlsafe`
+instead of `random.random()`"). Group by severity — a security sink or a
+resource leak outranks a missing type hint.
+
+```
+python-code-review: 3 findings
+  [security] auth.py:42 — `subprocess.run(cmd, shell=True)`; pass an
+    argument list instead
+  [resource] client.py:18 — `open()` with no `with`; the handle leaks if
+    `json.load` raises
+  [typing] models.py:9 — `def find(id) -> User:` has no param type and can
+    return `None`; add `id: int` and `-> User | None`
+```
+
+## Rules
+
+- NEVER edit the files under review — report findings only.
+- Cite the specific line and the specific safe alternative; a vague "this
+  could be an issue" finding is not actionable.
+- Do not duplicate a finding the project's own configured `ruff`/`mypy`
+  rules already enforce and would catch on their own — focus on what static
+  tooling misses (resource lifetime across exception paths, N+1 patterns,
+  logic bugs, security sinks needing call-site context).
+- Distinguish a real bug from a stylistic preference; a stylistic point
+  belongs in `rules/coding-style.mdc`/`rules/patterns.mdc`, not a review
+  finding blocking the change.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "The `except Exception` here is fine, it just logs" | Logging and continuing after swallowing an exception still hides the failure from the caller and from any monitoring keyed off the exception propagating |
+| "It's just a review, I'll fix the mutable default myself since it's a one-liner" | This skill is read-only; even a trivial fix belongs to the author or `python-build-fix`, not a silent edit during review |
+| "The N+1 loop only ever runs over 3 items in tests" | Test data size does not bound production data size; flag it regardless of the loop's current call sites |
+
+## Verification
+
+Do not report the review done until all of the following hold:
+
+- Every changed Python file in scope was checked against all seven
+  categories in Step 2.
+- No finding duplicates something the project's own configured linter/type
+  checker already flags and enforces.
+- Every finding names a file:line, the specific problem, and a specific
+  fix — no vague findings.
+- No file under review was modified.

package/src/gdskills/bundled/stacks/python/skills/python-code-review/evals.json

@@ -0,0 +1,72 @@
+{
+  "triggers": {
+    "positive": [
+      "Review this Python diff for mutable default argument bugs",
+      "Check this pull request for broad except clauses swallowing errors",
+      "Audit this Python module for resource leaks and unclosed files",
+      "Review this async Python code for blocking calls inside async def",
+      "Check this Python code review for typing holes like Any or missing Optional",
+      "Review this Django ORM code for N+1 query issues"
+    ],
+    "negative": [
+      "Implement a new Python feature that fetches user data",
+      "Write pytest tests for this module",
+      "Fix the mypy type errors so the build passes",
+      "Review this TypeScript React component for MobX store misuse",
+      "Run review-security-code on our whole repository for OWASP issues",
+      "Fix this ModuleNotFoundError in our Python package"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "mutable-default-finding",
+      "prompt": "Review this Python function for bugs:\n\ndef add_item(item, items=[]):\n    items.append(item)\n    return items",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct review flags `items=[]` as a mutable default argument that is created once and shared/mutated across every call that omits `items`, and gives the standard fix, without editing the code itself.",
+          "pass_criteria": [
+            "identifies that `items=[]` is a mutable default argument evaluated once at function definition, so it is shared and accumulates state across calls that don't pass their own list",
+            "gives the standard fix and shows the corrected code: default the parameter to `None` and create a new list inside the function body when it is `None`, e.g. `def add_item(item, items=None): if items is None: items = []` -- not just a description of the fix in the abstract",
+            "presents this as a specific finding on this function, not a generic style remark, and does not modify the code -- this skill only reports findings"
+          ],
+          "fail_criteria": [
+            "declares the function has no bug or is fine as written, missing the mutable-default issue entirely"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Finding: `add_item`'s `items=[]` default is a mutable default argument. Python evaluates default argument values once, at function-definition time, so every call to `add_item(item)` that omits `items` shares and mutates the exact same list object -- items appended in one call are still there on the next call, which is almost certainly not the intended behavior and will surface as a confusing bug wherever this is called more than once without an explicit `items=`. Fix: change the signature to `def add_item(item, items=None):` and create a fresh list inside the body when needed: `if items is None: items = []`. That guarantees each call that doesn't pass its own list gets a brand-new empty one instead of the shared default. This is a correctness bug, not a style nit, so I'd flag it as the primary finding here rather than suggesting an edit myself, since this review is read-only.",
+        "known_wrong": "This function looks fine to me -- `add_item` just appends an item to a list and returns it, which is exactly what it's supposed to do. The `items=[]` default is a convenient shortcut so callers don't have to pass an empty list every time; Python handles default arguments the same way most other languages do, evaluating them fresh per call. No changes needed here, the logic is straightforward and there's nothing that would cause unexpected behavior in normal use.",
+        "vague": "There's a subtle bug with the default list argument here -- mutable defaults in Python are generally risky and worth avoiding.",
+        "subtle_wrong": "Worth a note: `items=[]` is evaluated once at definition time, so calling `add_item` repeatedly without passing `items` would reuse the same list. I'd suggest switching to `items=None` with a fallback inside the body, though in practice this is more of a minor style nit than a real bug unless the function actually gets called that way in this codebase."
+      }
+    },
+    {
+      "id": "broad-except-finding",
+      "prompt": "Review this Python code:\n\ntry:\n    process(data)\nexcept Exception:\n    pass",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct review flags `except Exception: pass` as swallowing whatever error `process` raises rather than treating a broad catch that silently discards the error as acceptable.",
+          "pass_criteria": [
+            "identifies that `except Exception: pass` swallows the error instead of letting it propagate, being logged, or being handled specifically",
+            "explains the consequence: the caller and any monitoring keyed off the exception never see the failure, so real bugs go unnoticed",
+            "states this as a concrete finding, naming a specific alternative action -- log the exception with context (e.g. `logging.exception(...)`), re-raise, or catch a specific exception type -- not a vague 'handle it better'"
+          ],
+          "fail_criteria": [
+            "dismisses the bare `except Exception: pass` as fine or acceptable because it simply logs or prevents a crash, without flagging that the error is being hidden"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Finding: the bare `except Exception: pass` around `process(data)` swallows any error the call raises with no logging, no re-raise, and no fallback -- the failure just vanishes. If `process` fails for a genuinely unexpected reason (bad data, a downstream service error, a bug), nothing here surfaces it: the caller sees a silent no-op success, and any monitoring or alerting that depends on the exception propagating never fires. This also catches things a broad handler shouldn't, since `Exception` covers essentially every non-system-exiting error. At minimum this should log the exception with context before continuing, e.g. `logging.exception(\"process failed\")`, and ideally it should catch only the specific exception types `process` can legitimately raise and let anything else propagate, so real bugs aren't hidden behind a passing test run.",
+        "known_wrong": "This is fine -- catching `Exception` and passing just means a failure in `process(data)` won't crash the rest of the program, which is generally what you want in production code. It's a defensive pattern: if `process` has some edge case that throws, the surrounding code keeps running instead of taking down the whole request. I wouldn't flag this as a problem; if anything it shows the author was being careful about robustness. No changes needed.",
+        "vague": "This broad except could hide problems, so it would be safer to handle errors a bit more carefully here.",
+        "subtle_wrong": "Catching `Exception` is fine as a safety net so a failure in `process` doesn't take down the caller. I'd just add a one-line `logging.exception(\"process failed\")` before the `pass` so at least it's not completely silent -- keeps the same broad catch but gives you some visibility if it ever fires."
+      }
+    }
+  ]
+}

package/src/gdskills/bundled/stacks/python/skills/python-implementation/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: python-implementation
+description: "Use when implementing or extending a feature in a modern Python (3.12/3.13) codebase or service -- covers project tooling discovery (pyproject.toml, uv/poetry/pip, ruff, mypy/pyright), typing (generics, Protocol, TypedDict, dataclasses), context managers, exception chaining, asyncio TaskGroup, request/event logging with the standard logging module, and src/-layout packaging."
+triggers:
+  - "implement this in python"
+  - "add a python feature"
+  - "write a python function"
+  - "add a dataclass"
+  - "implement asyncio taskgroup"
+  - "add type hints to this module"
+  - "package this as a python module"
+  - "add a protocol class"
+  - "log requests in this python service"
+metadata:
+  origin: authored
+  category: implement
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Python implementation
+
+Implement or extend a feature in a modern Python (3.12/3.13) codebase:
+discovering the project's own tooling and conventions before writing code,
+then applying current-practice typing, resource management, error handling,
+concurrency, logging, and packaging patterns. Scoped to writing production
+code — for writing/fixing tests use `python-testing`, for reviewing a diff
+without editing it use `python-code-review`, for fixing a broken build/lint/
+type-check without adding a feature use `python-build-fix`.
+
+## Workflow
+
+### Step 1: Discover the project's own tooling and conventions
+
+1. Read `pyproject.toml` for: build backend, dependency manager (`uv`,
+   `poetry`, plain `pip`+`requirements.txt`), configured tools
+   (`[tool.ruff]`, `[tool.mypy]`/`[tool.pyright]`, `[tool.pytest.ini_options]`),
+   and the declared minimum Python version (`requires-python`).
+2. Confirm the package layout: `src/<package>/` (modern) vs. a flat
+   `<package>/` at repo root — place new modules consistently with what is
+   already there, don't introduce the other layout.
+3. Read 1-2 neighboring modules for: docstring style, typing style (PEP 604
+   `X | None` vs. `Optional[X]`), import grouping, and whether the project
+   already uses `from __future__ import annotations`.
+4. Check `requires-python`/CI config for the actual supported Python
+   versions before using a 3.12+-only feature (type-parameter syntax
+   `class Box[T]:`, `except*`) in a project that must also run on 3.11 or
+   earlier.
+
+### Step 2: Design the change
+
+- Prefer extending an existing module/class over adding a new one for a
+  small change; add a new module when the change introduces a genuinely new
+  concern.
+- Pick the data-modeling shape for the job: `@dataclass` for a fixed set of
+  related fields your own code constructs, `TypedDict` for a dict shape
+  that must stay a `dict` (e.g. JSON), `Protocol` for "anything with this
+  method" instead of a concrete base class, `Generic`/type-parameter syntax
+  for a container whose element type varies by call site. See
+  `rules/patterns.mdc` for the full set.
+- Decide error handling up front: which specific exception types the new
+  code raises, and which (if any) it must catch — never plan around a bare
+  `except:`/`except Exception:`.
+
+### Step 3: Implement
+
+1. Type-hint every new public function signature, including `| None`/
+   `Optional` where a parameter or return can be absent (match the
+   project's PEP 604 vs. `Optional` convention from Step 1).
+2. Acquire any closable/lockable resource with `with`/`async with`; write a
+   custom context manager with `@contextlib.contextmanager` unless the type
+   also needs other methods.
+3. Raise a specific exception type, chaining with `raise NewError(...) from
+   exc` when re-raising inside an `except` block.
+4. For concurrent work, group related awaitables with `asyncio.TaskGroup`
+   and let `asyncio.CancelledError` propagate through cleanup rather than
+   swallowing it; never call a blocking function inside `async def` (use
+   the async client, `asyncio.sleep`, or `asyncio.to_thread`).
+5. Log through the standard `logging` module (or the project's structured
+   logger) with lazy `%s` interpolation, not `print` or an f-string passed
+   to the logging call.
+6. Follow `rules/coding-style.mdc` for naming/formatting/imports and
+   `rules/patterns.mdc` for the rest of the idiom; check `rules/security.mdc`
+   before touching subprocess calls, deserialization, SQL, file paths, or
+   secrets.
+
+### Step 4: Verify
+
+```bash
+ruff check .
+ruff format --check .
+mypy .   # or: pyright
+pytest -x -q
+```
+
+Prefix each command with the project's own run prefix when it uses one
+(`uv run ruff check .`, `poetry run pytest -x -q`) — discovered in Step 1
+from `pyproject.toml`/lockfile presence, not assumed.
+
+### Step 5: Report
+
+```
+Implemented: src/mypkg/feature.py
+  - added `Widget` dataclass + `build_widget()`
+  - ruff/mypy/pytest: all green
+```
+
+## Rules
+
+- ALWAYS discover and match the project's own tooling (Step 1) before
+  assuming `uv`/`poetry`/`pip`, `mypy`/`pyright`, or a specific Python
+  version.
+- NEVER add `# type: ignore` or `# noqa` to route around a real typing or
+  lint problem — fix the underlying code, or narrow the suppression to the
+  one line with a comment explaining why it is correct as written.
+- NEVER use a Python version feature the project's `requires-python` does
+  not support.
+- Match the project's existing docstring style rather than introducing a
+  second one in the same file.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll just use `Any` here, typing this properly is fiddly" | Defeats the type checker for every downstream caller; use `Protocol`/`Generic`/a union instead, or `TypeVar` if the shape is genuinely generic |
+| "This helper doesn't need a `with` block, I'll just call `.close()` at the end" | Skips cleanup the moment an exception is raised before that line runs; use `with`/`try`/`finally` |
+| "I'll catch `Exception` broadly so nothing crashes" | Hides bugs in unrelated code paths as silently-ignored failures; catch the specific exception type you can actually handle |
+| "3.12 syntax is cleaner, I'll use it even though `requires-python` says 3.10" | Breaks on every environment still running the declared minimum version |
+
+## Verification
+
+Do not report the work done until all of the following hold:
+
+- New/touched public functions are type-hinted per Step 3.1, matching the
+  project's `Optional`/`| None` convention from Step 1.
+- `ruff check .`, `ruff format --check .`, and `mypy .`/`pyright` (or the
+  project's own configured equivalents) exit 0 on the touched files.
+- `pytest -x -q` (or the project's configured runner) passes; if a feature
+  needs new tests, hand off to `python-testing` rather than writing test
+  files as part of this skill's own change set when out of scope.
+- No bare `except:`/`except Exception:`, no unclosed resource, no blocking
+  call inside `async def`, introduced by this change.

package/src/gdskills/bundled/stacks/python/skills/python-implementation/evals.json

@@ -0,0 +1,78 @@
+{
+  "triggers": {
+    "positive": [
+      "Implement a Widget dataclass and a build_widget() function in src/mypkg/widgets.py",
+      "Add a new async function that fetches user records with asyncio.TaskGroup",
+      "Write a Python module that reads a config file and returns a typed Protocol object",
+      "I need to add type hints to this untyped Python function",
+      "Implement a context manager for our database connection pool in Python",
+      "Add a new feature to this Python service that logs each request with the logging module",
+      "Package this Python code with a src/ layout and pyproject.toml entry point"
+    ],
+    "negative": [
+      "Write pytest tests for the widgets module I just added",
+      "Review this Python pull request for bugs before I merge it",
+      "Fix this ModuleNotFoundError when importing mypkg.util",
+      "Implement this new feature in TypeScript for our Node service",
+      "Review the frontend React component for MobX store violations",
+      "Run a generic security audit across the whole repository"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "async-taskgroup-feature",
+      "prompt": "Implement a Python async function `fetch_all(urls)` that fetches several URLs concurrently and returns their results. Use current best practice for grouping the concurrent calls.",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "regex",
+          "value": "[Tt]ask[Gg]roup"
+        },
+        {
+          "grader": "judge",
+          "rubric": "A correct answer implements `fetch_all` using an async-compatible HTTP client and groups the concurrent fetches with `asyncio.TaskGroup` (structured concurrency), never a blocking synchronous call inside the async function.",
+          "pass_criteria": [
+            "groups the concurrent fetches with `asyncio.TaskGroup` in actual code, not merely stated as an intention -- a bare list of coroutines, `asyncio.gather`, or unmanaged `create_task` calls does not count",
+            "performs the HTTP fetch with an async-capable client (e.g. `httpx.AsyncClient`, `aiohttp`) shown in code, rather than a blocking call inside the coroutine",
+            "returns the aggregated results for all the URLs once the group completes"
+          ],
+          "fail_criteria": [
+            "calls a blocking function such as `requests.get` directly inside the async function instead of an async client. Mentioning it only to warn against it is not a failure."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "```python\nimport asyncio\nimport httpx\n\nasync def fetch_all(urls: list[str]) -> list[httpx.Response]:\n    results: list[httpx.Response] = [None] * len(urls)  # type: ignore[list-item]\n    async with httpx.AsyncClient() as client:\n        async with asyncio.TaskGroup() as tg:\n            async def fetch(i: int, url: str) -> None:\n                results[i] = await client.get(url)\n            for i, url in enumerate(urls):\n                tg.create_task(fetch(i, url))\n    return results\n```\nThis groups every fetch under one `asyncio.TaskGroup`, which gives correct sibling-cancellation: if one request fails, the group cancels the rest and raises an `ExceptionGroup` instead of leaving orphaned tasks running. Fetches go through `httpx.AsyncClient`, an async HTTP client -- never `requests.get`, which is a blocking call and would stall the event loop and defeat the concurrency entirely. Results are collected by index so the return order matches the input `urls` order.",
+        "known_wrong": "```python\nimport asyncio\nimport requests\n\nasync def fetch_all(urls):\n    results = []\n    for url in urls:\n        results.append(requests.get(url))\n    return results\n```\nThis loops through each URL and fetches it with `requests.get`, which is simple and reliable since `requests` is the standard, well-tested HTTP library everyone already knows. Wrapping the function in `async def` lets callers `await fetch_all(urls)` from other async code without needing a separate sync wrapper, and there's no need to pull in `asyncio.TaskGroup` or an async HTTP client just for a handful of URLs -- `requests.get` is a blocking function, but the sequential requests will still complete and return everything the caller needs.",
+        "vague": "Use asyncio to fire off the requests concurrently and gather the results with proper structured concurrency instead of doing them one at a time.",
+        "subtle_wrong": "```python\nimport asyncio\nimport httpx\n\nasync def fetch_all(urls):\n    async with httpx.AsyncClient() as client:\n        tasks = [asyncio.create_task(client.get(u)) for u in urls]\n        return await asyncio.gather(*tasks)\n```\nThis fires all the requests concurrently with `asyncio.create_task` and `asyncio.gather`, which is async and non-blocking throughout -- `gather` does the same job here with less new syntax, and this codebase hasn't adopted the newer structured-concurrency APIs yet."
+      }
+    },
+    {
+      "id": "resource-with-block",
+      "prompt": "Write a Python function that opens a file, reads its JSON contents, and returns the parsed data.",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer guarantees the file handle is closed on every path, including when parsing raises, parses the contents with the standard `json` module, and returns the parsed data.",
+          "pass_criteria": [
+            "the file handle is closed on every path, including when parsing raises -- a `with` block around `open(...)`, or an API that closes internally such as `Path.read_text()`/`Path.read_bytes()`, both satisfy this; a bare `open()` followed by a manual `.close()` that only runs on the happy path does not",
+            "parses the file's contents with `json.load`/`json.loads` and returns the resulting data",
+            "shows the actual code implementing this, not just a description of the approach"
+          ],
+          "fail_criteria": [
+            "opens the file without a `with` block and instead calls `.close()` manually at the end, so the handle leaks if an exception occurs before that line runs. Mentioning it only to warn against it is not a failure."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "```python\nimport json\nfrom pathlib import Path\n\ndef read_json(path: str | Path) -> object:\n    with open(path, \"r\", encoding=\"utf-8\") as f:\n        return json.load(f)\n```\nThe `with open(...)` context manager acquires the file handle and guarantees `f.close()` runs in every case -- including when `json.load(f)` raises because the file contains invalid JSON. I deliberately didn't write this as `f = open(path); data = json.load(f); f.close()`, since calling `.close()` at the end only runs on the happy path and leaks the handle whenever the line before it raises. `encoding=\"utf-8\"` is passed explicitly rather than relying on a platform default.",
+        "known_wrong": "```python\nimport json\n\ndef read_json(path):\n    f = open(path)\n    data = json.load(f)\n    f.close()\n    return data\n```\nThis opens the file, hands it to `json.load` to parse, and closes it right after before returning the parsed data -- straightforward and easy to follow line by line. Since `.close()` is called right after `json.load`, the handle doesn't stay open for long, so this should be fine for a normal config or data file without needing the extra `with` syntax.",
+        "vague": "Make sure the file handle gets closed properly even if the JSON turns out to be malformed, then return whatever was parsed.",
+        "subtle_wrong": "```python\nimport json\n\ndef read_json(path):\n    return json.loads(open(path).read())\n```\nThis opens the file and reads it in one expression -- Python's reference counting closes the handle as soon as the temporary file object goes out of scope, so there's no separate `.close()` call to remember, and it's a common one-liner for a quick read."
+      },
+      "anti_patterns": [".close()"]
+    }
+  ]
+}

package/src/gdskills/bundled/stacks/python/skills/python-testing/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: python-testing
+description: "Use when you write, extend, or fix a Python project's pytest suite -- add pytest.mark.parametrize cases, design conftest.py fixtures at the right scope, use pytest.mark.asyncio for coroutines, and patch external calls with mocker.patch/monkeypatch to close coverage gaps in a failing or incomplete test file. Not for auditing test conventions without changing files (see review-testing-practices)."
+triggers:
+  - "write pytest tests"
+  - "add python test coverage"
+  - "fix failing pytest test"
+  - "pytest fixture"
+  - "parametrize test"
+metadata:
+  origin: authored
+  category: test
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Python testing (pytest)
+
+Write, extend, or fix a Python project's `pytest` test suite. Scoped to
+pytest specifically — its fixture system, `parametrize`, and `monkeypatch`/
+`unittest.mock` conventions differ enough from a generic test-generation
+workflow (`quality/test-gen`) that a pytest-specific one earns its own
+skill; see `governance/scout.json` for why a fork of an existing skill was
+not enough.
+
+## Workflow
+
+### Step 1: Discover the project's pytest conventions
+
+1. Read `pyproject.toml`/`setup.cfg`/`pytest.ini` for `[tool.pytest.ini_options]`
+   or `[pytest]` — test paths, markers, `addopts` (e.g. `--strict-markers`,
+   coverage flags already configured).
+2. Find the test layout: `tests/` mirroring `src/`, or co-located
+   `test_*.py`/`*_test.py` next to the module under test. Match whichever
+   the project already uses.
+3. Read 1-2 neighboring test files for: fixture style (local `conftest.py`
+   vs. inline), naming (`test_<behavior>`), assertion style (plain
+   `assert` vs. a matcher library), and how mocks are constructed.
+
+### Step 2: Plan fixtures before test cases
+
+- A fixture needed by just one test module belongs in that module — define
+  it directly in the test file. Promote it to a `conftest.py` only once a
+  second test file needs the same fixture, and then place it in the
+  narrowest `conftest.py` that covers every file needing it (the shared
+  directory, not the suite root).
+- Prefer a fixture's natural scope (`function` is the pytest default) over
+  widening to `module`/`session` for convenience; a wider-scoped fixture
+  that mutates state leaks between tests that assumed isolation.
+- Use `pytest.fixture(params=[...])` or a `@pytest.mark.parametrize` on the
+  test itself for input variations — parametrize the test when only the
+  inputs vary, use a fixture when setup/teardown logic itself varies.
+
+### Step 3: Plan test cases
+
+**Functions:** happy path, edge cases (empty/`None`/zero/negative),
+exception cases (`pytest.raises(SpecificError)`), boundary values.
+
+**Fixtures/context managers:** setup ran, teardown ran even when the body
+raises, correct value yielded.
+
+**Async code:** `pytest.mark.asyncio` (or the project's configured async
+plugin) — do not write a sync test that silently never awaits the coroutine
+under test.
+
+**Mocks:** patch at the point of use (`mocker.patch("mypkg.mod.dep")`, not
+the definition site), and only external dependencies — an internal
+collaborator mocked away stops the test verifying real integration.
+
+### Step 4: Write
+
+1. Create/extend the test file at the project's own convention path.
+2. Import fixtures via `conftest.py` discovery, not manual re-import.
+3. One assertion concept per test; a multi-assertion test states in its
+   name what single behavior it verifies.
+4. Use `pytest.mark.parametrize` with explicit `ids=` when parameter tuples
+   are not self-describing in pytest's default output.
+
+### Step 5: Run and fix
+
+```bash
+keryx test run --changed --strict
+```
+
+`src/testing/service.ts` detects the project's own test runner from its
+lockfile/scripts — do not hard-code `pytest` invocation flags here beyond
+what Step 1 already discovered. On a project with no keryx testing config,
+run the project's own configured `pytest` invocation instead.
+
+Fix failing tests (max 3 iterations) — fix the test, not the source under
+test.
+
+### Step 6: Report
+
+```
+Generated: tests/test_helper.py
+  - 9 test cases (3 parametrized), all passing
+```
+
+## Rules
+
+- ALWAYS match the project's existing fixture/parametrize/mock conventions
+  found in Step 1-2, not a different project's pytest style.
+- NEVER modify source code — only test files and `conftest.py`.
+- Mock external dependencies (network, filesystem, other services), not
+  internal modules under the same package.
+- If no `pytest` is configured, suggest adding it; do not add it
+  unasked.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "This fixture is only used once but I'll put it in the root `conftest.py` anyway" | Widens its visible scope and discoverability for no reason; a fixture needed by just one test file belongs directly in that file, not in any `conftest.py`, until a second file needs it |
+| "The assertion keeps failing; I'll patch the source under test to make it pass" | This skill writes test files only. A source change buried in a test-authoring run is an unreviewed fix that also hides the real bug |
+| "I'll mock the internal helper so the test is simpler" | Mock external dependencies, not internal ones — a test whose internal collaborators are all mocked only checks that the mocks agree with each other |
+| "Still failing after three iterations; I'll loosen the assertion" | A test that asserts nothing covers nothing while reporting coverage. After 3 iterations, stop and report the failing case instead |
+
+## Verification
+
+Do not report the work done until all of the following hold:
+
+- The test file sits at the project's own convention path, matching the
+  fixture/parametrize/mock style read in Step 1-2.
+- `keryx test run --changed --strict` — or, with no keryx testing config,
+  the project's own discovered `pytest` command — exits 0 with every
+  generated test passing.
+- `git status` shows only test files (and `conftest.py`, if touched)
+  added or modified; no source file under test changed.
+- Every exported function/class/endpoint identified in Step 1 that lacked
+  coverage now has at least one test, or the report says why it does not.