Skip to content

v2.0.0 — Rename to mlx-porting + checkerboard pitfall + CI

Choose a tag to compare

@dgrauet dgrauet released this 20 Apr 00:23
· 10 commits to main since this release

Breaking

  • Skill directory renamed porting-pytorch-to-mlx/mlx-porting/. Same move inside the packaged .skill tarball.
  • Frontmatter name updated accordingly: mlx-porting.
  • Existing v1.0.0 installs (the ~/.claude/skills/porting-pytorch-to-mlx/ layout) will keep working but will NOT receive these updates — reinstall from source or download the new mlx-porting.skill artifact below.

Added

  • Pitfall #7 — The checkerboard trap in references/common-pitfalls.md. Covers the four recurring causes (mx.tile vs mx.repeat, pixel-shuffle axis order, text-encoder hidden_states[-2] off-by-one, scheduler dtype leaking fp32 into a bf16 DiT) and a three-test diagnostic procedure to run before shipping every port.
  • SKILL.md upgrades: new reading-time checklist bullet flagging the checkerboard trap, plus a caveat in Step 5 that small-scale random-weight parity is necessary but insufficient.
  • Helpers in scripts/parity_helpers.py: `detect_checkerboard(image)` (autocorrelation-based) and `noise_decode_check(decode_fn, shape)` to wire the diagnostic as a permanent smoke test.
  • GitHub Actions:
    • `ci.yml` validates frontmatter, `evals.json` schema, cross-references, and python syntax on every push and PR, plus a `.skill` packaging smoke test.
    • `release.yml` auto-builds `mlx-porting.skill` on tag push and attaches it to the release (this release is the first to use it).
  • CI badge on the README.

Why this matters

Every MLX port I've shipped has hit a checkerboard-looking output at some point because layer-level parity passes with random weights at small scale but the bug only manifests at production scale. This release codifies the fix: the 3-test diagnostic catches 95% of the class in under 90 seconds, and the rule "never tweak sampling parameters to mask a spatial-operator bug" is now part of the checklist.

Asset

`mlx-porting.skill` below is produced by the new release workflow. Drop it into Claude Code via `/skill install mlx-porting.skill` or unpack under `~/.claude/skills/`.