@mrciphersmith/keryx 0.2.164 → 0.3.0

package/src/gdskills/bundled/stacks/python/governance/scout.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Use when a Python project's pytest test suite needs writing, extending, or fixing -- covers fixture design, parametrization, mocking, and coverage gaps in existing pytest test files.",
+    "decision": "fork",
+    "topMatch": "review/review-testing-practices",
+    "recordedAt": "2026-09-24T04:48:38.183Z",
+    "skillName": "python-testing",
+    "justification": "top match review/review-testing-practices (0.37) is a review skill that checks existing tests against convention, not an authoring workflow; quality/test-gen (0.23) is a generic cross-language test generator with no pytest-specific fixture/parametrization/mocking guidance and no stack awareness. Decision is fork (below use threshold 0.55), and neither candidate is a substitute for a stack-scoped pytest authoring skill, so create."
+  },
+  {
+    "query": "Use when implementing or extending a feature in a modern Python (3.12/3.13) codebase -- covers project tooling discovery (pyproject.toml, uv/poetry/pip, ruff, mypy/pyright), typing (generics, Protocol, TypedDict, dataclasses), context managers, exception chaining, asyncio TaskGroup, logging, and src/-layout packaging.",
+    "decision": "create",
+    "topMatch": "python/python-build-fix",
+    "recordedAt": "2026-09-24T11:57:31.665Z",
+    "skillName": "python-implementation",
+    "justification": "top match python/python-build-fix (0.23) only shares generic Python-tooling vocabulary (mypy, ruff, pyright, pip/poetry) from its own build-fix scope, not implementation/typing/asyncio guidance; go/go-implementation (0.15) is a different language's implementation skill. Decision is create (below fork threshold 0.3), so a Python-specific implementation skill is genuinely new."
+  },
+  {
+    "query": "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.",
+    "decision": "fork",
+    "topMatch": "ts-js-node/nodejs-code-review",
+    "recordedAt": "2026-09-24T11:58:18.113Z",
+    "skillName": "python-code-review",
+    "justification": "top match ts-js-node/nodejs-code-review (0.40) is the same review category but for a different language stack (JS/TS-specific mutable-default/resource/async checks do not transfer to Python's own except/typing/ORM idioms); go/go-code-review (0.22) is likewise a different language. Decision is fork (below use threshold 0.55, above fork threshold 0.3): the review category is shared across stacks by design, but no candidate covers Python's own mutable-default/except/async/typing/N+1/security vocabulary, so a Python-scoped fork is warranted."
+  },
+  {
+    "query": "Use when a Python project fails to import, build, type-check, or lint -- resolves ModuleNotFoundError/ImportError, packaging or editable-install failures, dependency resolver conflicts (pip/uv/poetry), mypy/pyright type errors, ruff failures, and pytest collection errors with the smallest root-cause fix.",
+    "decision": "fork",
+    "topMatch": "ts-js-node/nodejs-build-fix",
+    "recordedAt": "2026-09-24T11:58:25.230Z",
+    "skillName": "python-build-fix",
+    "justification": "top match ts-js-node/nodejs-build-fix (0.45) and go/go-build-fix (0.37) are the same build-fix category but for other languages' own toolchains (npm/tsc vs. pip/uv/mypy/ruff), not substitutes; python/python-implementation (0.33) is this same pack's implementation skill, sharing only generic tooling-discovery vocabulary, not a build-fix workflow. Decision is fork (below use threshold 0.55, above fork threshold 0.3): the build-fix category is shared across stacks by design, but no candidate resolves Python-specific ModuleNotFoundError/packaging/resolver/mypy/ruff/pytest-collection failures, so a Python-scoped fork is warranted."
+  }
+]

package/src/gdskills/bundled/stacks/python/pack.json

@@ -0,0 +1,41 @@
+{
+  "id": "python",
+  "family": "language",
+  "modules": ["python-rules", "python-skills"],
+  "detectionMarkers": ["python"],
+  "provenance": {
+    "origin": "authored",
+    "sourceRef": "flow 309 (W1 Lane D), completed in flow 314"
+  },
+  "stability": "stable",
+  "skills": {
+    "implement": ["python-implementation"],
+    "test": ["python-testing"],
+    "review": ["python-code-review"],
+    "build-fix": ["python-build-fix"],
+    "migrate": []
+  },
+  "agentProfile": {
+    "displayName": "Python",
+    "auditFocus": [
+      "mutable default arguments (`def f(x=[])`) instead of `None` + inside-body init",
+      "broad `except:`/`except Exception:` that swallows an unrelated failure",
+      "resource handles (files, sockets, DB connections, locks) opened without a `with` block",
+      "blocking calls (`requests`, `time.sleep`, sync file I/O) inside an `async def`",
+      "typing holes: untyped public signatures, bare `Any`, or an implicit-`None` return missing `| None`/`Optional`",
+      "security sinks: `shell=True`, `eval`/`exec`, `pickle`/`yaml.load` on untrusted input, unparameterized SQL"
+    ],
+    "buildCommands": [
+      "ruff check .",
+      "ruff format --check .",
+      "mypy . || pyright",
+      "pytest -x -q"
+    ],
+    "fixGuardrails": [
+      "never add `# type: ignore` or `# noqa` to silence a checker without fixing or explaining the underlying issue",
+      "never pin or downgrade a dependency to route around a real incompatibility without saying so in the report",
+      "never widen a narrowed exception catch or a real type hole just to make a check pass",
+      "fix the smallest root cause; do not refactor unrelated code while resolving a build/lint/type failure"
+    ]
+  }
+}

package/src/gdskills/bundled/stacks/python/rules/coding-style.mdc

@@ -0,0 +1,63 @@
+---
+extends: common
+paths: ["**/*.py", "**/*.pyi"]
+metadata:
+  origin: authored
+---
+
+# Python coding style
+
+Narrows `core-common-rules`' stack-agnostic style rules to Python's own
+idiom. Applies only to `*.py`/`*.pyi` files — everything not
+Python-specific still comes from the common rules this file `extends`.
+
+## Formatting and typing
+
+- Format with the project's configured formatter (`ruff format` or `black`);
+  do not hand-format around a formatter that is already configured.
+- Type-hint every new or touched public function signature (`def f(x: int)
+  -> str:`), including `Optional`/`| None` for a parameter or return that can
+  be absent. Do not add hints to untouched code in the same change.
+- Prefer `from __future__ import annotations` in modules that predate PEP 604
+  (`int | None`) rather than importing `Optional`/`Union` piecemeal.
+- Use `pathlib.Path`, not `os.path` string joins, for new filesystem code.
+- Use f-strings for interpolation in normal code (`f"{name} joined"`), not
+  `%`-formatting or `.format()` — except in logging calls, where lazy `%s`
+  interpolation is correct (see `rules/patterns.mdc`).
+- Run `ruff check .` (or the project's configured equivalent) instead of
+  hand-checking unused imports, shadowed builtins, or import order; fix what
+  it flags rather than adding a blanket `# noqa`.
+
+## Naming and structure
+
+- `snake_case` for functions, variables and modules; `PascalCase` for
+  classes; `UPPER_SNAKE_CASE` for module-level constants — the PEP 8
+  baseline, not a house variant of it.
+- One public class or cohesive function group per module; a module that
+  outgrows one screen's worth of unrelated public names should split.
+- Private module/class internals get a single leading underscore
+  (`_helper`), not name-mangled double-underscore unless subclass
+  name-clash protection is the actual intent.
+
+## Errors and imports
+
+- Raise a specific exception type (`ValueError`, `KeyError`, or a project
+  exception class), never a bare `except:` or `except Exception:` that
+  swallows an unrelated failure — catch the specific type you can handle.
+- Absolute imports (`from mypackage.module import thing`), not relative
+  dot-imports (`from ..module import thing`), for anything crossing a
+  package boundary; relative imports are fine within one package's own
+  submodules.
+- Group imports stdlib / third-party / local, each group alphabetized, one
+  blank line between groups — the convention `isort`/`ruff --select I`
+  enforce; run it instead of hand-ordering when the project has it
+  configured.
+
+## Docstrings
+
+- Every public function, class and module gets a docstring stating what it
+  does and, for a function with non-obvious parameters, what each one means
+  — a one-line summary is enough when the signature is already
+  self-describing.
+- Match the project's existing docstring convention (Google-style, NumPy-style,
+  or plain reST) rather than introducing a second style in one file.

package/src/gdskills/bundled/stacks/python/rules/patterns.mdc

@@ -0,0 +1,88 @@
+---
+extends: common
+paths: ["**/*.py", "**/*.pyi"]
+metadata:
+  origin: authored
+---
+
+# Python patterns
+
+Narrows `core-common-rules`' stack-agnostic design guidance to idiomatic
+Python 3.12/3.13 patterns and the anti-patterns they replace. Applies only to
+`*.py`/`*.pyi` files.
+
+## Data and typing
+
+- Model a fixed set of related fields with `@dataclass` (or `attrs` if the
+  project already depends on it) instead of a `dict` with string keys — a
+  typo in a dict key fails at runtime, a typo in a dataclass field fails at
+  lint/type-check time.
+- Use `TypedDict` for a dict shape that genuinely must stay a `dict` (e.g. a
+  JSON payload), not for data your own code constructs and passes around.
+- Reach for `typing.Protocol` to type "anything with this method" instead of
+  requiring a concrete base class when the caller only needs structural
+  compatibility — this keeps callers free to pass any matching object.
+- Use `Generic[T]`/type parameter syntax (`class Box[T]:` on 3.12+) for a
+  container or wrapper whose element type varies by call site, rather than
+  typing it `Any` and re-casting at every use.
+
+## Control flow and resources
+
+- Acquire any closable/lockable resource (file, socket, DB connection, lock,
+  temp directory) with a `with` (or `async with`) block; never rely on `del`,
+  garbage collection, or a manual `.close()` that a raised exception can skip.
+- Write a custom context manager as a generator decorated
+  `@contextlib.contextmanager` rather than a hand-rolled
+  `__enter__`/`__exit__` class, unless the class also needs other methods.
+- Raise a new exception `from` the one being handled
+  (`raise ValueError(...) from exc`) instead of a bare `raise ValueError(...)`
+  inside an `except` block — this preserves the causal chain instead of
+  presenting the new exception as unrelated.
+- Prefer early return over nested `if`/`else` for guard conditions; a
+  function whose happy path is indented inside three levels of conditionals
+  should invert its guards.
+
+## Async
+
+- Group a set of related concurrent awaitables with `asyncio.TaskGroup`
+  (3.11+) instead of manually tracking a list of tasks and awaiting them
+  with `asyncio.gather` — a `TaskGroup` cancels its siblings automatically
+  when one fails.
+- Treat `asyncio.CancelledError` as a signal to clean up and re-raise. Since
+  Python 3.8 it subclasses `BaseException`, not `Exception`, so a broad
+  `except Exception` does *not* catch it; only a bare `except:` or an
+  explicit `except BaseException` does, and either one must re-raise it
+  rather than swallow it.
+- Never call a blocking function (`requests.get`, `time.sleep`, synchronous
+  file I/O, a CPU-bound loop) directly inside an `async def` — use the async
+  client, `asyncio.sleep`, or `asyncio.to_thread`/an executor instead.
+
+## Iteration and collections
+
+- Prefer a generator or generator expression over building an intermediate
+  list when the caller only iterates the result once.
+- Use `itertools`/`collections` (`defaultdict`, `Counter`, `chain`,
+  `groupby`) instead of hand-rolled loops that reimplement them.
+- Avoid a mutable default argument (`def f(items=[])`); default to `None`
+  and initialize inside the function body — a mutable default is shared and
+  mutated across every call that omits the argument.
+
+## Logging
+
+- Use the standard `logging` module (or the project's configured structured
+  logger), not `print`, for anything beyond a throwaway script.
+- Pass interpolation arguments to the logging call
+  (`logger.info("got %s", value)`), not an f-string
+  (`logger.info(f"got {value}")`) — the f-string formats even when the log
+  level is disabled, and the lazy form does not.
+
+## Anti-patterns to flag, not introduce
+
+- Wrapping an entire function body in `try/except Exception: pass` to make a
+  flaky call "just work" — this hides real failures instead of handling the
+  specific one expected.
+- Reassigning a loop variable's type mid-loop, or reusing one name for two
+  unrelated purposes in the same function — confuses both readers and type
+  checkers.
+- Deep inheritance chains built to share a few methods — prefer composition
+  or a `Protocol` unless the hierarchy models a genuine is-a relationship.

package/src/gdskills/bundled/stacks/python/rules/security.mdc

@@ -0,0 +1,84 @@
+---
+extends: common
+paths: ["**/*.py", "**/*.pyi"]
+metadata:
+  origin: authored
+---
+
+# Python security
+
+Narrows `core-common-rules`' stack-agnostic security guidance to Python's own
+OWASP-style sinks and the safe API each one has a direct replacement for.
+Applies only to `*.py`/`*.pyi` files.
+
+## Command and code execution
+
+- Never call `subprocess.run`/`Popen`/`call` with `shell=True` or a single
+  interpolated command string; pass an argument list
+  (`subprocess.run(["cmd", arg])`) so the shell never re-parses untrusted
+  input.
+- Never pass untrusted input to `eval`/`exec`, `compile()` of untrusted
+  source, or `os.system` — there is no safe way to sandbox these; parse the
+  input with a real parser (`json`, `ast.literal_eval` for literals) instead.
+- Treat `ast.literal_eval` as the only acceptable "eval-like" call on
+  untrusted text, and only for literal Python values, never arbitrary
+  expressions.
+
+## Deserialization
+
+- Never unpickle (`pickle.load`/`loads`, `dill`, `shelve`) data from a
+  source you do not fully trust and control — unpickling untrusted bytes is
+  equivalent to `exec`. Use `json` or a schema-validated format instead.
+- Use `yaml.safe_load`, never `yaml.load`, for any YAML that did not
+  originate from your own trusted config in the repo.
+- Parse XML with `defusedxml` instead of raw
+  `xml.etree.ElementTree`/`xml.dom.minidom` on untrusted input. Current
+  `xml.etree`/expat no longer fetch external entities by default, so classic
+  XXE is not the risk; the remaining risk is entity-expansion ("billion
+  laughs") and similar resource-exhaustion DoS attacks, which the stdlib
+  parsers do not guard against and `ET.parse` has no option to disable —
+  `defusedxml` is still the safe choice for untrusted input.
+
+## Data access
+
+- Build SQL with parameterized queries (`cursor.execute("... WHERE id = %s",
+  (id,))` or the ORM's own query builder), never by interpolating values
+  into a SQL string with f-strings/`%`/`.format()`.
+- Validate and normalize any filesystem path built from user input before
+  using it; resolve with `Path(...).resolve()` and check it stays under the
+  intended base directory to prevent path traversal (`../../etc/passwd`).
+
+## Secrets and randomness
+
+- Generate tokens, session IDs, and password-reset codes with the `secrets`
+  module (`secrets.token_urlsafe`, `secrets.compare_digest`), never `random`
+  — `random` is not cryptographically secure and its output is predictable.
+- Never hard-code a credential, API key, or secret in source; read it from
+  the project's configured secret store or environment, and never log it.
+
+## Network calls
+
+- Always pass an explicit `timeout` to `requests`/`httpx` calls — an
+  unbounded call to a slow or hung endpoint can hang the whole process.
+- Never set `verify=False` (requests) or disable TLS certificate validation
+  to work around a cert error; fix the underlying trust-store/cert issue
+  instead.
+
+## Dependencies
+
+- Run the project's dependency audit tool (`pip-audit`, or `uv pip list
+  --outdated` plus the project's configured scanner) before adding a new
+  third-party dependency with security-sensitive functionality (auth,
+  crypto, deserialization, subprocess wrapping).
+- Pin dependencies the project already pins (lockfile present) rather than
+  loosening a version constraint to resolve a conflict without checking the
+  changelog for the versions in between.
+
+## Red flags
+
+- "I'll just use `shell=True` here, the input is only ever a filename" — an
+  attacker-controlled filename can still contain shell metacharacters;
+  always pass an argument list.
+- "`eval` is fine, this string only comes from our own config file" — if the
+  config file is ever user-editable or fetched remotely, this stops being
+  true; prefer `ast.literal_eval` or `json.loads` regardless.

package/src/gdskills/bundled/stacks/python/rules/testing.mdc

@@ -0,0 +1,77 @@
+---
+extends: common
+paths: ["**/*.py", "**/*.pyi"]
+metadata:
+  origin: authored
+---
+
+# Python testing
+
+Narrows `core-common-rules`' stack-agnostic testing guidance to `pytest`
+conventions. Applies only to `*.py`/`*.pyi` files; see
+`skills/python-testing/SKILL.md` for the full test-authoring workflow this
+rule file backs.
+
+## Layout and discovery
+
+- Match the project's existing layout: a `tests/` tree mirroring `src/`, or
+  co-located `test_*.py`/`*_test.py` files — do not introduce the other
+  layout alongside it.
+- Name test files, classes, and functions so `pytest`'s default discovery
+  finds them (`test_*.py`/`*_test.py`, `Test*` classes with no `__init__`,
+  `test_*` functions) rather than relying on manual `testpaths` overrides.
+- Keep a fixture in the narrowest `conftest.py` that covers every test
+  needing it; do not hoist a single-file fixture to the suite root.
+
+## Fixtures and parametrization
+
+- Prefer the pytest default `function` scope; widen to `module`/`session`
+  only for expensive, read-only setup, and never for a fixture that mutates
+  shared state.
+- Use `@pytest.mark.parametrize` when only inputs vary; use a fixture (or
+  `pytest.fixture(params=[...])`) when setup/teardown logic itself varies
+  between cases.
+- Give parametrized cases explicit `ids=` when the parameter values are not
+  self-describing in pytest's default test-ID output.
+
+## Mocking
+
+- Patch at the point of use (`mocker.patch("mypkg.module.dependency")`), not
+  at the dependency's definition site.
+- Mock only external dependencies (network, filesystem, other services,
+  wall-clock time); an internal collaborator mocked away stops the test
+  verifying real integration between your own modules.
+- Prefer `unittest.mock.AsyncMock` (or `pytest-mock`'s `mocker.patch` with
+  `new=AsyncMock()`) for mocking an `async def` dependency, not a plain
+  `Mock` that returns a coroutine-shaped object nothing ever awaits.
+
+## Async tests
+
+- Mark an async test with `pytest.mark.asyncio` (or the project's configured
+  async plugin/mode) — a sync test function that merely calls a coroutine
+  without awaiting it silently never runs the coroutine's body.
+- Use the project's configured event-loop fixture scope; do not create a new
+  event loop per test unless the project's async plugin requires it.
+
+## Determinism
+
+- Never depend on real wall-clock time, network access, or filesystem state
+  outside a fixture-managed temp directory (`tmp_path`) — freeze time
+  (`freezegun` or the project's equivalent) and mock the network.
+- Never depend on dict/set iteration order for test correctness beyond
+  Python's own guaranteed dict insertion order; sort collections before
+  comparing when the underlying data structure does not guarantee order.
+- A flaky test (passes/fails nondeterministically) gets fixed at its root
+  cause (a missing await, an unmocked clock, a race) — never retried into
+  passing or skipped to hide the flake.
+
+## Coverage expectations
+
+- Every new or touched public function/class/endpoint gets at least one
+  test covering its happy path, its documented edge cases, and any raised
+  exception type.
+- A test asserts one behavior; a test with several unrelated assertions
+  should split so a failure names the specific behavior that broke.
+- Run the project's configured coverage tool (`pytest --cov` when
+  configured) and treat an uncovered branch in touched code as a gap to
+  close, not to suppress with a `# pragma: no cover` on real logic.

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

@@ -0,0 +1,144 @@
+---
+name: python-build-fix
+description: "Use when a Python project fails to import, build, type-check, or lint -- resolves ModuleNotFoundError/ImportError, packaging or editable-install failures, dependency resolver conflicts (pip/uv/poetry), mypy/pyright type errors, ruff failures, and pytest collection errors with the smallest root-cause fix."
+triggers:
+  - "fix this ModuleNotFoundError"
+  - "python import is failing"
+  - "mypy is failing"
+  - "ruff check is failing"
+  - "pip dependency conflict"
+  - "pytest collection error"
+  - "editable install is broken"
+metadata:
+  origin: authored
+  category: build-fix
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Python build-fix
+
+Resolve a broken Python build, import, dependency, type-check, or lint
+failure with the smallest change that fixes the actual cause. Scoped to
+making the toolchain green again — for adding a feature use
+`python-implementation`, for writing/fixing test *content* (not a collection
+error) use `python-testing`, for reviewing without fixing use
+`python-code-review`.
+
+## Workflow
+
+### Step 1: Reproduce and classify the failure
+
+Run the project's own configured commands (from `pyproject.toml`, discover
+the run prefix — `uv run`, `poetry run`, or none):
+
+```bash
+ruff check .
+ruff format --check .
+mypy .   # or: pyright
+pytest -x -q
+```
+
+Read the *first* error in each tool's output — later errors are often
+downstream of the first. Classify:
+
+- **Import/ModuleNotFoundError** — package not installed, wrong environment
+  active, circular import, or a typo'd module path.
+- **Packaging/editable install** — `pip install -e .` fails, or an installed
+  package's modules aren't importable (missing `__init__.py`, wrong `src/`
+  layout declared in `pyproject.toml`'s `[tool.hatch.build]`/
+  `[build-system]`).
+- **Dependency resolver conflict** — `pip`/`uv`/`poetry` reports
+  incompatible version constraints between two dependencies.
+- **Type errors** — `mypy`/`pyright` reports a real type mismatch.
+- **Lint failures** — `ruff check` reports a rule violation.
+- **Pytest collection errors** — a test file fails to import (distinct from
+  a test that runs and fails).
+
+### Step 2: Find the root cause
+
+- **ModuleNotFoundError**: is the package installed in the active
+  environment (`pip show <pkg>` / `uv pip show <pkg>`)? Is the import path
+  correct relative to the project's `src/`-layout or flat layout? Is this a
+  circular import (`A` imports `B` which imports `A`) that needs a
+  restructure (move the shared symbol, or import inside the function) — not
+  a `try/except ImportError` wrapper.
+- **Packaging/editable install**: check `[build-system]` and the package
+  discovery config (`[tool.setuptools.packages.find]` or `[tool.hatch.build]`)
+  actually points at the real package directory; a missing `__init__.py` in
+  a namespace-package-by-mistake is a common cause.
+- **Dependency conflict**: read the resolver's own explanation of which two
+  constraints collide; find the actual compatible version range (check the
+  conflicting packages' own changelogs/release notes) rather than force-
+  installing with `--no-deps` or pinning to an arbitrary older version.
+- **Type errors**: read the exact mismatch mypy/pyright reports; fix the
+  signature or the call site — whichever is actually wrong given the
+  function's real contract, not whichever silences the error fastest.
+- **Lint failures**: apply `ruff check --fix .` for genuinely mechanical
+  fixes (unused imports, import order); for a substantive rule (unused
+  variable that indicates a real bug, `S`-prefixed security rule) fix the
+  code, don't suppress the rule.
+- **Pytest collection errors**: usually an import error in the test file or
+  `conftest.py` itself — apply the same import-error diagnosis above to the
+  test file's own imports.
+
+### Step 3: Apply the smallest fix
+
+- Fix the actual cause identified in Step 2 — the missing dependency, the
+  wrong import path, the real type mismatch, the actual lint violation.
+- When a version conflict is genuinely unresolvable without a larger
+  upgrade, say so explicitly in the report rather than silently pinning
+  around it.
+- Touch only what the failure requires; do not refactor unrelated code
+  while fixing a build failure.
+
+### Step 4: Verify
+
+Re-run every command from Step 1 in order; all must exit 0. Also run
+`pytest -x -q` even when the original failure was only a lint/type error —
+a fix can introduce a runtime regression the linter/type-checker won't see.
+
+### Step 5: Report
+
+```
+Fixed: ModuleNotFoundError: No module named 'mypkg.parsers'
+  Root cause: src/mypkg/parsers.py existed but pyproject.toml's package-find
+    config excluded src/mypkg/, so the editable install never linked it.
+  Fix: added "mypkg*" to [tool.setuptools.packages.find].include
+  Verified: ruff check, mypy, pytest -x -q all green
+```
+
+## Rules
+
+- NEVER add `# type: ignore` or `# noqa` as a blanket suppression to make a
+  real error disappear without fixing or explicitly justifying it inline.
+- NEVER pin, downgrade, or `--no-deps` install a dependency to route around
+  a real conflict without stating in the report that this is a workaround
+  and why a proper fix wasn't available.
+- NEVER wrap a real ImportError in `try/except ImportError: pass` to hide a
+  missing dependency — install/declare it, or fix the import path.
+- Fix the root cause with the smallest change; do not refactor beyond what
+  the failure requires.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll just add `# type: ignore` here, the real fix is bigger" | Hides the type hole permanently; if the real fix is out of scope, say so in the report and leave the error visible rather than silently suppressing it |
+| "I'll pin this package to the old version that worked" | Papers over an incompatibility that will resurface; identify the actual compatible range or report that a larger upgrade is needed |
+| "The test file won't import, I'll just skip it with `pytest.mark.skip`" | A collection error means the test never runs at all; skipping hides that permanently instead of fixing the import |
+| "`ruff check --fix` didn't fix everything, I'll disable the rule in `pyproject.toml`" | Disabling a rule project-wide silences it for all future code, not just this failure; fix the flagged code instead |
+
+## Verification
+
+Do not report the fix done until all of the following hold:
+
+- The originally failing command now exits 0.
+- `ruff check .`, `ruff format --check .`, `mypy .`/`pyright`, and
+  `pytest -x -q` (the project's own configured equivalents) all exit 0.
+- No new `# type: ignore`/`# noqa` was added without an inline reason, and
+  none was added as a blanket suppression.
+- `git status` shows only the files whose actual cause was diagnosed in
+  Step 2 — no unrelated refactor.
+- The report names the root cause, not just the symptom that was fixed.

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

@@ -0,0 +1,74 @@
+{
+  "triggers": {
+    "positive": [
+      "Fix this ModuleNotFoundError: No module named 'mypkg.util'",
+      "Our editable pip install is broken, the package won't import",
+      "mypy is failing with a type error I don't understand, please fix it",
+      "ruff check is failing on our CI, fix the violations",
+      "pip is reporting a dependency resolver conflict between two packages",
+      "pytest collection is erroring out before any tests even run"
+    ],
+    "negative": [
+      "Implement a new feature that uses asyncio.TaskGroup",
+      "Write pytest tests for the new widgets module",
+      "Review this Python diff for security issues",
+      "Fix the TypeScript build failure in our Node service",
+      "Run a full test-generation pass over this untested module",
+      "Review this code for architecture violations"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "module-not-found-diagnosis",
+      "prompt": "Our Python project fails with `ModuleNotFoundError: No module named 'mypkg.util'` when running pytest. How do you diagnose and fix this?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer diagnoses the actual cause of the ModuleNotFoundError (the package not installed in the active environment, a wrong import path relative to the project's layout, or a circular import) before proposing a fix, and the fix addresses that cause rather than hiding the failure.",
+          "pass_criteria": [
+            "identifies a concrete root cause: the package/module is not installed or the wrong environment is active, the import path is wrong for the project's src/flat layout, or the failure is a circular import",
+            "applies a fix matched to that cause and names the concrete action taken -- the actual install command (e.g. `pip install -e .`), the corrected import path, or the specific packaging-config key changed -- not just 'fix the packaging config' in the abstract",
+            "distinguishes the root cause from the symptom in how it explains or reports the fix, instead of only restating the traceback"
+          ],
+          "fail_criteria": [
+            "recommends wrapping the failing import in try/except ImportError (e.g. `try/except ImportError: pass`) to hide the failure instead of fixing it. Mentioning the suppression only to warn against it is not a failure."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "First check whether the environment ModuleNotFoundError is actually happening in has mypkg installed: run `pip show mypkg` (or `uv pip show mypkg`) in the same environment pytest uses. If it's missing or the wrong virtualenv is active, install it (`pip install -e .` from the project root) so the active env matches what's configured in pyproject.toml. If the package is installed, check whether mypkg/util.py actually exists at the path the import expects given the project's src/ or flat layout, and whether the package-discovery config in pyproject.toml (`[tool.setuptools.packages.find]` or `[tool.hatch.build]`) actually includes that subpackage. Also check for a circular import: does util.py import something that eventually imports back into util itself? If so, restructure by moving the shared symbol or importing inside the function, not by wrapping the import in try/except ImportError. Once fixed, rerun pytest and confirm the module imports cleanly and the report states the actual root cause found.",
+        "known_wrong": "Easiest fix: add a try/except ImportError around the import so pytest doesn't crash.\n\n```python\ntry:\n    from mypkg.util import helper\nexcept ImportError:\n    helper = None\n```\n\nThis way the module loads even if mypkg.util isn't available in this environment, and any code that calls helper() just gets None back instead of crashing at import time. You can leave the rest of the code as-is and run pytest again -- it should collect without the ModuleNotFoundError now. If something later needs helper for real, you can always properly install the package then, but for now this unblocks the test run without having to chase down whether it's a packaging config issue or an environment problem.",
+        "vague": "Check whether the module is actually available in the environment running pytest, and make sure the import path lines up with how the project is laid out, then re-run the tests instead of working around the error.",
+        "subtle_wrong": "This is happening because mypkg isn't installed in the environment pytest uses. Rather than chasing down the packaging config, I added `sys.path.insert(0, \"src\")` to the top of conftest.py so the import resolves locally without a real install, and pytest collects cleanly now."
+      },
+      "anti_patterns": ["try/except ImportError"]
+    },
+    {
+      "id": "mypy-error-no-blanket-suppress",
+      "prompt": "mypy reports a type error on a function I touched. Fix it.",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer fixes the real type mismatch mypy reported -- by correcting the function's signature/annotation or the call site that violates it -- rather than making the error disappear with a blanket suppression. Because the prompt supplies neither the error text nor the code, an answer that first asks for the exact mypy message and the touched function, while explicitly ruling out a suppression as the eventual fix, is also correct: it cannot name the concrete mismatch without that information, and asking for it is the honest move.",
+          "pass_criteria": [
+            "either names the exact mismatch mypy reported (the signature, the annotation, or the call site's type) and changes that code to resolve it, or -- since neither the error text nor the code was given -- asks for the actual mypy message and the touched function before proposing a fix",
+            "commits to fixing the real mismatch once it is identified or known: the annotation, the call site, or a narrowing -- never treats a suppression as the fix itself",
+            "explicitly refuses a blanket `# type: ignore`/`# noqa` suppression, a loosened mypy config, or retyping the parameter/return as `Any` as a substitute for the real fix"
+          ],
+          "fail_criteria": [
+            "adds `# type: ignore` (bare or blanket) or `# noqa`, loosens the mypy config (e.g. disables the check globally), or retypes the value as `Any` to make the error disappear, instead of fixing or asking about the actual mismatch. Mentioning the suppression only to warn against it is not a failure."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Read mypy's exact message first -- it names the mismatch, e.g. \"Argument 1 to 'process' has incompatible type 'str'; expected 'int'\". Look at the function's real contract: does `process` genuinely only make sense for `int`, or was the parameter always meant to accept both? If the function should accept `int`, fix the call site to pass an int (or convert it) instead of touching the signature. If the function's contract is actually broader than what's declared, widen the annotation to `int | str` and adjust the body to handle both cases correctly. Either way, don't add `# type: ignore` on the line just to quiet mypy -- that hides the real hole for every future caller. Once the annotation and the call sites agree with what the function actually does, rerun `mypy .` to confirm it's clean, and rerun pytest since a signature change can affect runtime behavior too.",
+        "known_wrong": "mypy is being overly strict here, the code works fine at runtime. Simplest fix is to just silence it:\n\n```python\ndef process(value) -> None:  # type: ignore\n    ...\n```\n\nThat clears the error mypy was reporting without needing to dig into why the annotation didn't match the call site -- the function still behaves the same, mypy just stops complaining. You can move on to the actual feature work instead of spending time chasing down whether the argument type or the annotation was the one that was wrong.",
+        "vague": "Take a look at what mypy is complaining about in that function and adjust the type so it lines up correctly, instead of just suppressing the warning.",
+        "subtle_wrong": "mypy's message is annoying but I don't have time to dig into why the annotation doesn't match the call site right now, so I added `# type: ignore[arg-type]` on that one line -- it's scoped to just that error code, not a blanket ignore, and I left a comment saying it's temporary until we get back to the real fix."
+      },
+      "anti_patterns": ["# type: ignore"]
+    }
+  ]
+}