| name | release-api-freeze-review |
| description | Pre-release feature and public API freeze audit for torchfits. Inventories exports, cross-checks docs/parity/examples against code and tests, verifies release gates and benchmark claims. Use for feature freeze, API freeze, 0.5.0b4, pre-release review, or public API audit before tagging. |
| disable-model-invocation | true |
Release API freeze review (torchfits)
Use before tagging a beta/final when the release claims feature-freeze and API-freeze.
Outputs
Write findings to docs/reviews/release-api-freeze-<version>.md with sections:
- Verdict — Ship / Ship with notes / Block
- Blocking — must fix before tag
- Should-fix — fix before tag if time allows
- Defer to next minor — document only
- Evidence gaps — parity rows without tests
Phase 1 — Public surface inventory
python .cursor/skills/release-api-freeze-review/scripts/inventory_public_api.py
- Compare script output to
docs/api.md Quick Paths and src/torchfits/__init__.py __all__
- Flag: undocumented exports, documented-but-missing symbols, deprecated aliases without notice
- Check lazy namespaces:
table, cache, cpp
Phase 2 — Docs contract
Read and cross-check:
| Doc | Check |
|---|
README.md | No out-of-scope claims; performance cites docs/benchmarks.md run ID |
docs/api.md | Every Quick Path entry resolves; env vars documented |
docs/parity.md | Each Supported row has test evidence |
docs/examples.md | Every example path exists and runs |
docs/changelog.md | Unreleased section matches diff |
docs/release.md | Version triplet matches pyproject.toml, pixi.toml, __init__.py |
Run: pixi run pytest tests/test_docs_integrity.py -q
Phase 3 — Behavior & defaults
Audit high-impact defaults (breaking if changed post-freeze):
read(..., scale_on_device=True), mmap="auto", device="cpu"table.read(..., where=) pushdown policy env vars- GPU integer paths (signed-byte, unsigned convention)
- Deprecations:
read_image → read_tensor
Phase 4 — Release gates
pixi run release-gate
pixi run -e bench-gpu release-gate
pixi run pytest tests/test_examples_runner.py -q
Phase 5 — Benchmark claims
- Latest snapshot in
docs/benchmarks.md BENCH_SNAPSHOT matches a benchmarks_results/<run-id>/ directory
- README performance table uses same run ID
- Deficit count documented honestly
Phase 6 — Freeze verdict
| Criterion | Pass? |
|---|
| No undocumented public exports | |
| Parity Supported rows backed by tests | |
| release-gate green (CPU + GPU if available) | |
| Examples runnable | |
| Version/changelog aligned | |
| No README/docs scope creep (WCS/sphere/HEALPix) | |
API-freeze rule: After this review passes, only bugfixes and doc corrections until tag — no new public symbols or signature changes without bumping beta suffix and changelog entry.
Companion reviews (run separately)
/thermo-nuclear-code-quality-review — maintainability (not API surface)/review-bugbot — diff bugs/review-security — security on branch diff
