ByteTerrace/Puck / .claude/skills/maths-usage
maths-usage
VerifiedPicks Puck.Maths primitives and determinism rules: FixedQ4816, FixedVector3, rate accumulators, Pcg32XshRr, AliasTable, Fnv1aHash, rounding, saturation, primes. Law cases: maths-laws.
references/complete-reference.md
View on GitHub# Maths-usage complete reference
Read the section `SKILL.md` routes here for. The wing READMEs own each
contract; this file maps a question to its wing and states the cross-wing
rules.
## Contents
- [First contact](#first-contact)
- [Choose the primitive](#1-choose-the-primitive)
- [Determinism contract](#2-obey-the-determinism-contract)
- [Verification](#3-verify)
- [Governance](#4-governance)
## First contact
Puck.Maths is the engine's **deterministic numerics** library: a leaf project
with no dependencies whose promise is that the same inputs return the same bits
on every machine, backend and run, so a simulation built on it can be recorded,
replayed and compared byte for byte. It replaces floating point on the
simulation value path with binary fixed-point scalars, vectors, rotations and
world positions; reproducible randomness that can be saved mid-sequence and
resumed; exact finite fields; exact integer and real-quadratic arithmetic; and a
presented-algebra tier for graph, lattice and language questions. It is
organized as **eight wings** — one folder and one README each — plus a set of
root-level types. The **human** entry point (prose, worked examples, the full
root catalogue) is
[Deterministic numerics](../../../../docs/reference/maths.md); this file is the
agent's.
| Your question | Wing | What lives there | Read first |
|---|---|---|---|
| Which number type? How does this round, wrap or saturate? A position, a velocity, a rotation, a transform, a rate integrated over ticks | [FixedPoint](../../../../src/Puck.Maths/FixedPoint/README.md) | Signed and unsigned Q48.16 (and the Q32.32 split), the unit-interval fractions, vectors, complex/dual/split, quaternions, rigid transforms, `FixedPosition`, the rate accumulators, `FixedInterval`, mass properties and symmetric solves, `CurvatureSpline`, and the fused-arithmetic and text substrate | "Choosing a scalar", then "Load-bearing invariants" |
| Randomness of any shape — a roll, a weighted pick, noise, scatter, a shuffle, a Monte Carlo estimator — or a seed / stream / snapshot question | [Sampling](../../../../src/Puck.Maths/Sampling/README.md) | `Pcg32XshRr`, `WeightedSampler`/`AliasTable<T>`, `Pcg3dLatticeNoise`, `LowDiscrepancy`, `DigitalNetSampler`, `StratifiedShuffle`, `InvertibleBitMix`, `ConeDirectionTable`, `SecureRandom`, `ProbabilityFunctions` | "Choosing a primitive", then "The rules a consumer inherits" |
| Arithmetic that must be **exact** — mod p, `GF(2^k)`, region arithmetic over a span of field values, a primality decision | [FiniteFields](../../../../src/Puck.Maths/FiniteFields/README.md) | `BinaryPolynomial`, `BinaryField<T>` (k = 1…128 over a packed carrier), the canonical `BinaryFields` moduli, `PrimeField64`, `QuadraticExtensionField64` | "At a glance", then "Primality on `ulong`" |
| One relation over several carriers; "is this construction a special case of something the library already has?" | [Algebra](../../../../src/Puck.Maths/Algebra/README.md) | `QuadraticAlgebra<TScalar>`, `GeometricAlgebra`/`Multivector`, `MonogenicAlgebra<TScalar>`, `DoublingAlgebra<TInner>`/`IConjugationRing<TSelf>` | "At a glance" — then §4 here before proposing a collapse |
| Grids and index spaces — hex cells, tile/chunk order, rings and shells, an exact 2×2 integer transform | [Geometry](../../../../src/Puck.Maths/Geometry/README.md) | `HexagonalCoordinate`, `HilbertCurve`, `LayerSequence`, `ModularTransform` | "At a glance" |
| The subject is a graph, a lattice, a language or a finite structure rather than a number — reachability, convolution and inversion, pattern matching, homology, group orbits | [Oracle](../../../../src/Puck.Maths/Oracle/README.md) | One presented-algebra product over swappable materials: `Presentations`, `PresentedAlgebra`, `DivisibilityAlgebra`, `TokenPattern`/`PatternMatcher`, `ExteriorCalculus`/`IntegerHomology`, `ReflectionSystem`/`PresentedGroup` | "Choosing an entry point", then "Contracts every consumer inherits" |
| An exploratory or open-problem question — continued-fraction tails, Sturmian and quasicrystal words, Fibonacci and metallic means, real-quadratic orders | [Research](../../../../src/Puck.Maths/Research/README.md) | Exact, certificate-bearing, off the hot path; a budget-exhausted search (`SearchLimitReached`) is never conflated with a proof or a counterexample | "At a glance" — and the namespace split stated above it |
| A frequency- or sequency-domain transform, or a cyclic convolution | [Transforms](../../../../src/Puck.Maths/Transforms/README.md) | Exact: `NumberTheoreticTransform`/`NumberTheoreticTransformPlan` (over `PrimeField64`), `WalshHadamardTransform` (any binary integer, no plan). Fixed-point, measured bounds: `FixedFourierTransform`/`FixedFourierTransformPlan` (over `FixedComplex`), `FixedCosineTransform`/`FixedCosineTransformPlan` (over `FixedQ4816`). All in place; `Convolve` on both spectral transforms | "At a glance", then the transform's own section |
| Primality over `ulong`, and nth-prime or prime counts within `uint` | root level (owns no wing) | `PrimeExtensions.IsPrime`, `NthPrime(uint)` and `PrimeCountingFunction(uint)` | [Prime exploration](../../../../docs/reference/prime-exploration.md) |
| A per-tick state hash, an exact allocation over intervals, bucket routing, a tie-broken sort order, an exact real-quadratic value, a bit trick or a GCD | root level (owns no wing) | `Fnv1aHash`, `DiscreteMeasure`/`CompiledDiscreteMeasure64`, `MonotonicPartitioner`, `LexicographicOrder`, `RealQuadratic`, `ContinuedFraction`, `CyclicRotation`, `SymmetryLattice`, `NumberTheoryFunctions`, and the integer kit (`BinaryIntegerFunctions`, `UnsignedNumberFunctions`, `PrimeExtensions`) | [Root-level types](../../../../docs/reference/maths.md#root-level-types) |
**Depth lives in the wing READMEs**, and this skill never restates their
contract tables or re-argues a rule they own. When one disagrees with this file,
**the wing wins**.
**Namespace.** Everything is flat `Puck.Maths`, except part of `Research/`,
which is `Puck.Maths.Research` — that wing's README lists which side each type
is on.
---
## 1. Choose the primitive
### Scalars
| The quantity is… | Use | Not |
|---|---|---|
| Signed, has an integer part — position, velocity, accumulated advance | `FixedQ4816` (Q48.16, `long` carrier) | a `float`/`double`; a bare `long` scaled by hand |
| The same, but genuinely cannot be negative | `UFixedQ4816` (UQ48.16) | `FixedQ4816` plus an assertion |
| A fraction in `[0, 1)` — blend factor, normalized coordinate, sub-pixel offset | `UnitFraction16` (2⁻¹⁶) or `UnitFraction32` (2⁻³²) | a Q48.16 you promise stays under one |
| A value that must be able to *reach* 1 — probability, certainty, membership, a weight meaning "all the way" | `UnitInterval32` (closed `[0, 1]`, `ulong` carrier) | `UnitFraction32` — it has **no** `One`, no `MultiplicativeIdentity`, no `++`, by design |
| A count, an index, a tick, a bitfield, a raw carrier you are about to reinterpret | a plain integer | a fixed-point type |
**Choose signedness deliberately.** Helpers constrained to `IUnsignedNumber<T>`
accept only the non-negative types, so the choice propagates. The full decision
is [Choosing a scalar](../../../../src/Puck.Maths/FixedPoint/README.md#choosing-a-scalar).
**A raw `long` is the wrong type** whenever the value has a scale. A hand-scaled
integer carries its exponent in a comment, so its rounding, its overflow
behaviour and its text form are all re-invented locally and none of them are
gated. The one legitimate raw is a value crossing a byte boundary — a snapshot,
the `Puck.Scripting` addon ABI — and it round-trips through
`FixedQ4816.FromRawBits` / `.Value`, never through arithmetic.
**`UnitInterval32` costs a thirty-third bit and buys three things** a Q0.32
cannot have: a multiplicative identity, exact absorbing elements at both ends,
and closure of `Multiply` (one rounding, ties to even) over the whole interval.
It has **no arithmetic operators at all** — every combining operation is a named
method (`Multiply`, `AddSaturating`, `SumExcess`, `Complement`, `Min`, `Max`),
because `UnitFraction32` shares the grid and reads `~`, `+` and `-` differently.
`FromUnitFraction32` carries a sampler draw in exactly; `TryToUnitFraction32`
carries it back whenever it is still below one.
### Vectors, rotations, transforms, positions
| You need | Use |
|---|---|
| A 2D/3D displacement | `FixedVector2` / `FixedVector3` |
| A 2D rotation | `FixedComplex` (`FromAngle`, `*` composes, `Rotate` applies) |
| A 3D rotation | `FixedQuaternion` (`FromAxisAngle`, `Slerp`, `FromTo`) |
| A rotation *and* a translation as one object | `FixedRigidTransform` (a unit dual quaternion; `ScLerp` interpolates the screw) |
| A world position beyond a small scene | `FixedPosition` — 64-bit cell indices plus a centred local offset, the floating-origin coordinate. A `FixedVector3` alone is a **displacement**, not a position |
| A scaling / rate-composition flow | `FixedSplit` (`j² = +1`, `FromRapidity`) |
| A forward-mode sensitivity | `FixedDual<FixedQ4816>` (`FixedDual.Variable` seeds it) |
| Rate → quantity over ticks, with no drift | `FixedRateAccumulator` / `FixedVector3RateAccumulator` — the sub-unit division remainder carries across calls, and **is authoritative snapshot state** |
| To interpolate or clamp | `FixedQ4816.Lerp` / `.Clamp`, `FixedVector2.Lerp` / `FixedVector3.Lerp`, `FixedQuaternion.Slerp`, `FixedRigidTransform.ScLerp`. Never a hand-rolled `a + (b − a)·t` |
| A pole-matched second-order response (a target that eases, overshoots, or anticipates rather than snapping) | `SecondOrderDynamics` (`FixedPoint/SecondOrderDynamics.cs`) — `Create(f, ζ, r)` derives the coefficients once, `Compile(stepTicks, ticksPerSecond)` gives a `SecondOrderStep` for a per-tick/per-frame `Step`, `Evaluate(y0, v0, target, elapsedTicks, ticksPerSecond)` is the closed form for a lazily-read state cell. A float twin ([SecondOrderFollower](../../../../src/Puck.SdfVm/Views/SecondOrderFollower.cs)) exists for presentation-only followers (camera booms, stamped parts); never feed it back into simulation state |
Products in this family are **fused**: the whole expression accumulates exactly
and the result rounds once per returned component. Do not decompose one into
pairwise operations.
### Sampling — one shape of randomness each, and they do not overlap
| You need | Use | State? |
|---|---|---|
| Sequential draws over time — rolls, wander, decisions | `Pcg32XshRr` | **Yes** — it is simulation state |
| A weighted pick | `WeightedSampler.Create` once at load → `AliasTable<T>.Sample` (O(1), two advances plus an exact wide draw on a rare word; reports `advances`) | Immutable table |
| Spatial randomness — terrain, wind, per-cell decisions, a scattered point | `Pcg3dLatticeNoise` (`ValueNoise01`, `ScatterPoint`, `Pcg3d`) | None |
| Points that merely spread out — scatter, placement | `LowDiscrepancy.R1` / `R2` | None |
| Stratification as a **theorem** — Monte Carlo, area lights, anything averaged | `DigitalNetSampler` | None |
| Security-sensitive draws | `SecureRandom` — and **never** in simulation state; it is deliberately non-reproducible | Hidden platform state |
| A permutation of a list | `Pcg32XshRr.Shuffle` (in-place Fisher–Yates) | Uses the generator's state |
`LowDiscrepancy` and `DigitalNetSampler` have the same shape (index in, point
out, no state). The net's guarantee is strictly stronger: the additive
recurrences equidistribute asymptotically and stratify *nothing* exactly. Reach
for the net only when the estimator's error actually depends on stratification.
**One stream per system**, derived from the run's master seed with a small
consecutive id (`Pcg32XshRr.Create(state: masterSeed, stream: id)`); persist
`State`/`Increment`/`Multiplier` with the world and restore through
`FromRawBits`; never build `Advance`-based seeking on a rejection-sampling draw
(`NextUInt32(min, max)`, `Shuffle`). Those three, and the fourth beside them
(alias tables are order-sensitive), are the wing's own contract; the argument
for each is at
[the rules a consumer inherits](../../../../src/Puck.Maths/Sampling/README.md#the-rules-a-consumer-inherits).
### Grids, index spaces, hashing, exact integers
| You need | Use | Wing |
|---|---|---|
| A hex grid whose 60° rotations are exact | `HexagonalCoordinate` (Eisenstein integers) | [Geometry](../../../../src/Puck.Maths/Geometry/README.md#hexagonalcoordinate) |
| Locality-preserving tile/chunk order | `HilbertCurve`, not Morton (`BinaryIntegerFunctions.BitwisePair`) | [Geometry](../../../../src/Puck.Maths/Geometry/README.md#hilbertcurve) |
| Rings, shells, shards — index → layer in constant time | `LayerSequence` | [Geometry](../../../../src/Puck.Maths/Geometry/README.md#layersequence) |
| A per-tick state hash for a determinism or replay probe | `Fnv1aHash` — allocation-free, endianness-independent | root level |
| An exact integer allocation over intervals (jobs/frame, samples/frame) | `DiscreteMeasure` → `CompiledDiscreteMeasure64` for the hot path | root level |
| An exact rational, reduced on construction, for authoring and compile-time derivations that round once at the end | `Rational` | root level |
| An exact real-quadratic value — `RealQuadraticField` names the field `ℚ(√d)`, `RealQuadratic` carries the value with conjugate, norm and trace | `RealQuadratic` | root level |
| Bit tricks, GCD, integer roots, pairing, factorization | `BinaryIntegerFunctions`, `UnsignedNumberFunctions`, `PrimeExtensions` | root level |
| The Nth prime or the prime count through a `uint` bound | `PrimeExtensions.NthPrime(uint)` / `PrimeCountingFunction(uint)` (zero-based index) | [Prime exploration](../../../../docs/reference/prime-exploration.md) |
| A low mask exact at 0 and the full width, power-of-two alignment, PDEP/PEXT, a 2-D or 3-D Morton code — never a hand-rolled `(1 << n) - 1`, `(x + a - 1) & ~(a - 1)` or `Bmi2` call | `BinaryIntegerFunctions.LowMask`, `AlignUp`/`AlignDown`, `ParallelBitDeposit`/`ParallelBitExtract`, `BitwisePair`/`BitwiseTriple` | [Bit kit](../../../../docs/reference/maths.md#bit-kit) |
| One relation over several carriers, or a proof two carriers agree | `QuadraticAlgebra<TScalar>` and the structure tier | [Algebra](../../../../src/Puck.Maths/Algebra/README.md) |
### Finite fields
`BinaryField<T>` is `GF(2^k)` for k in 1…128 over a bare packed carrier
(`byte`…`UInt128`), so a region of field values is just a span; the canonical
minimum-weight moduli are `BinaryFields.Degree8/16/32/64/128`.
`BinaryPolynomial` is the `GF(2)[t]` ring beneath it. `ReedSolomon` sits on
`BinaryField<T>` and does systematic coding over any of them — generator,
check symbols, syndromes — so an error-correcting consumer builds a code rather
than a field of its own; a consumer whose standard names a modulus the catalog
does not carry constructs it with `BinaryField<T>.Create`, which precomputes
nothing. `PrimeField64` is `F_p` for an odd prime below 2⁶², with
`QuadraticExtensionField64` for `F_{p²}`.
Field products are **exact** — associative, commutative, distributive, with an
exact inverse for every non-zero element — so unlike a rounded fixed-point
product they *are* safe to reassociate. `PrimeExtensions.IsPrime` is this library's
exact decision for every `ulong`: the uint kernel for narrow inputs and
`IsBaillieProbablePrime` for wider inputs. Baillie–PSW with Selfridge Method A
is exact on this finite carrier by published exhaustive computation; the
[FiniteFields reference](../../../../src/Puck.Maths/FiniteFields/README.md#primality-on-ulong)
owns the source and algorithm match. `IsStrongProbablePrime` and
`IsStrongLucasProbablePrime` alone admit pseudoprimes. Never use the forwarding
`IsPrime` entry point as an independent oracle for the composition.
### The presented-algebra tier (`Oracle/`)
Reach for it when the question is about a **graph, a lattice, a language, or a
finite structure** rather than about a number: reachability, shortest paths,
walk counts, best-probability or bottleneck routes (`Presentations.Quiver` at
the matching material), Dirichlet convolution and Möbius inversion
(`DivisibilityAlgebra`), pattern matching where a language *is* an element
(`TokenPattern` → `PatternMatcher`), homology with torsion (`ExteriorCalculus`
→ `IntegerHomology`), group words and orbits (`ReflectionSystem` →
`PresentedGroup`). One product serves all of them; the material chooses the
arithmetic. `PresentedAlgebra.Residual` is the one derivative operator with
three twists — `Counit` gives the left quotient (Brzozowski's derivative),
`Identity` gives an ordinary derivation whose unit coefficient *is* `FixedDual`'s
chain rule bit for bit, and `ShiftGenerator` gives the skew step behind
holonomic recurrences — all satisfying one twisted Leibniz rule rather than
three code paths. Entry points and the contracts every consumer inherits:
[Oracle](../../../../src/Puck.Maths/Oracle/README.md#choosing-an-entry-point).
An algebra instance is **not** safe for concurrent use; the presentation it
wraps is immutable and shareable.
---
## 2. Obey the determinism contract
**Determinism pins the mapping, not the values.** Same document + same input →
bit-identical state on every run, machine and backend *at a fixed code version*.
It is not output stability across versions: a deliberate correction to maths is
*expected* to move state hashes. Never preserve a wrong result to keep a hash
stable, and never add a path that reproduces old-wrong behaviour.
- **No floating point in simulation state.** Two boundaries only: authoring in
(`FromDouble`, a run-document weight) and presentation out (`(double)`,
`ToVector3`, `ToQuaternion`, `ToComplex`, `FixedPosition.ToRenderRelative`).
A **seam** is a boundary where a value passes from one world into another, and
**presentation seams are one-way** — nothing they return flows back into
state. Which conversions are seams, and why the `double`-taking direction is
still deterministic, is the
[FixedPoint wing's opening](../../../../src/Puck.Maths/FixedPoint/README.md).
- **A floating-point estimate may propose; integers decide.** Inside an exact
integer kernel, a binary64 value may choose work (a narrow prime rank
estimate) or propose a candidate that exact integer arithmetic then accepts
or corrects (a bounded quotient estimate and exact remainder correction).
That is not floating point in state, provided the result is
exact for every input in the stated domain and the error bound that makes
it so is written beside the code, with a law at the bound's edges.
- **Wrap is the default; saturation and refusal are named.** Bare operators are
unchecked; `checked` forms throw *after* the operation's rounding;
`AddSaturating`/`SubtractSaturating` clamp on the unsigned and unit types and
`FixedSaturate` clamps `FixedQ4816` and vectors. Some saturators have **no**
`Try…` sibling, so do not assume a member reports its boundary — the unpaired
ones are enumerated at
[load-bearing invariants](../../../../src/Puck.Maths/FixedPoint/README.md#load-bearing-invariants).
- **Ties go to even, and there are exactly three exceptions** — `Exp2`,
`Log2` and `Atan2`, which narrow half up. Each says so at the member and the
wing argues why (`SinCos` is ties-to-even). Assume ties-to-even everywhere
else; do not invent a fourth exception, and do not "correct" one of the three.
- **Do not reassociate a rounded product.** `INumber<T>` grants capabilities,
not a proof that multiplication is associative: `(a·b)·c ≠ a·(b·c)` at some
operands over `FixedQ4816`. The fused kernels exist so a whole expression
rounds once, and the suite's divergence canaries fail if one is decomposed.
Finite-field products are the exception — exact, therefore reassociable.
- **Do not hand-roll what the library provides.** A second implementation can
silently diverge in rounding, overflow, or floor/ceiling convention. Before
writing a lerp, clamp, integer square root, GCD, floor division, bit mixer,
2×2 integer matrix, continued-fraction step, or rate/remainder carrier,
search for it (route through `content-search` in the main `SKILL.md`). If the
shape genuinely is missing, add it to the library rather than beside it.
Signed floor/ceiling division is the one this tree has re-grown most often,
and a hash-bearing caller makes the divergence class determinism-adjacent:
route every one through `BinaryIntegerFunctions.FloorDivide`/`CeilingDivide`,
which are correct for a negative dividend where the built-in `/` truncates
toward zero.
- **Bound an unbounded search from inside it, with two clauses.** A search whose
termination rests on a theorem rather than on a validation — the Selfridge
parameter walk, the descent to the smallest non-residue — fails by HANGING,
and a hang is not a red test. Such a loop owes two guards with **distinct**
messages: a deterministic step budget, which says the predicate is broken,
and a wrap guard, which says the range is exhausted. Both, because they catch
different things: a next-prime walk from `2⁶⁴ − 40` that steps past the
carrier wraps and answers **3**, a wrong answer no budget can catch. Prefer a
deterministic bound to a wall-clock timeout wherever the loop is
instrumentable; a timeout puts machine speed into a pass/fail verdict. The one
exception is a guard inside a primitive whose termination rests on its own
validations, where a budget masks a validation gap instead of exposing it.
- **Results do not depend on ambient culture, locale, or CPU features.** The
hardware paths (`PDEP`/`PEXT` in the bit routines, the carryless multiply and
region ladders in the fields) are bit-identical to their portable fallbacks,
and that equivalence is *gated* — see
[FiniteFields → Verifying changes](../../../../src/Puck.Maths/FiniteFields/README.md#verifying-changes).
A hardware path is taken only where it is also fast: `PDEP`/`PEXT` are
microcoded on AMD before Zen 3 (the Steam Deck's Zen 2 included) and on Hygon's
licensed Zen 1, with a mask-dependent latency of up to hundreds of cycles, so
every `PDEP`/`PEXT` site
tests `BitManipulation.HasFastParallelBits`, never `Bmi2.IsSupported`, and that
one gate is the only vendor-specific branch in the library. Its decision is the
pure `BitManipulation.IsParallelBitsFast(vendor, family, hasBmi2)`, pinned by
`integer.fast-parallel-bits-decision-table`; see the
[bit kit](../../../../docs/reference/maths.md#bit-kit).
Parameterless formatting and parsing are invariant; explicit providers are
honored deterministically.
---
## 3. Verify
`tests/Puck.Maths.Tests` is the machine-checked story a `src/Puck.Maths` change
gets: a three-tier suite of law cases.
**Is a contract claim actually tested?** Every case is declared in
`tests/Puck.Maths.Tests/laws/<family>.json` with the public members it covers
and the legs it stands on, and `LawRegistry.cs` (with its per-family partials)
binds each id to the code that runs it. Member coverage is declared in those rows and waivers live in `Coverage.cs`.
**The quick check: one command.** It is the cheapest way to see a change under
`src/Puck.Maths` working, whichever wing it touched:
```text
dotnet build tests/Puck.Maths.Tests/Puck.Maths.Tests.csproj -c Release -nodeReuse:false
dotnet test tests/Puck.Maths.Tests/Puck.Maths.Tests.csproj -c Release --no-build
```
(The build is its own command: [verification](../../verification/SKILL.md#build-before-you-test)
says why.) That is the Default tier, the ordinary run. It is
where structural completeness and evidence declarations are checked directly,
without any recorded artifact.
**The tier ladder.** Higher tiers are explicit, opted into per run, and are *not* to be
fired on every change. Their cost is the point: they buy breadth you do not need
in a change loop.
| Tier | Command | Budget | When |
|---|---|---|---|
| **Default** | *(a plain run — no filter)* | ordinary | the quick check for a change |
| Deep | `--explicit on --filter-trait tier=Deep` | broader | optional breadth, worth it for a rounding change |
| Exhaustive | `--explicit on --filter-trait tier=Exhaustive` | long | on demand or nightly; full-carrier sweeps and expensive finite combinatorial-prime checks, as classified by `maths-laws` |
**Do not run the `Exhaustive` tier reflexively.** It takes tens of minutes;
narrow it with `--explicit on --filter-display-name '<law-id>*'` when one law is the question. Run it only
when the member you touched names it as its gate of record, which
the law declarations and `Coverage.cs`'s waiver reasons will tell you by
name. When in doubt, check the waiver rather than running the tier.
To find the cases that cover a member, search the declarations for its name:
`puck search -M 0 '"Name": "<Member>"' tests/Puck.Maths.Tests/laws`. The row's
`Id` prefix is the family, and a file's name need not match its family:
`laws/world-coord.json` covers only `BinaryIntegerFunctions` (family `core`),
`laws/digital-net.json` holds `sampling.*` cases, and `laws/doubling-tower.json`
holds `algebra.*` cases. The wing READMEs' "Verifying changes" sections name the
families that matter for each wing, for example
[Algebra → Verifying changes](../../../../src/Puck.Maths/Algebra/README.md#verifying-changes).
The `exhaustive.prime-selection-*` cases carry the published 10^15 and 10^16
prime counts and ranks.
**What green means, and does not.** A green battery means no probe failed. It
does not by itself mean no probe *diverged*: a defect that turns a subject
predicate uniformly false can spin a search helper rather than trip an
assertion, which is why every unbounded search whose predicate is a subject
carries a step budget whose exhaustion is a named failure. Read the exit code
*and* the section output.
**Land a new public member with its classification.** A law case (a
`laws/<family>.json` declaration naming the member, bound in `LawRegistry.cs`)
or a waiver with a reason in `Coverage.WaiverDeclarations`.
`LawCompletenessTests` validates declared references and waiver reasons without
a recorded baseline; `LawDeclarationTests` holds declaration/binding parity.
Authoring the case or the waiver itself belongs to
[`maths-laws`](../../maths-laws/SKILL.md).
**When documentation and behaviour disagree, correct their owning sources.**
A structural leg whose citation opens `DOC GAP:` records the precise mismatch
in its authored law declaration; close it by correcting the doc or code and the leg.
**A changed hash after a deliberate correction is not a failure.** Re-record a
persisted replay or baseline the correction invalidates when you next run it.
---
## 4. Governance
A specialized primitive collapses into the generic algebra tier when the
generic replacement carries the **same correctness and the same performance**.
No retained artifact holds the performance evidence behind the existing type
boundaries, and the `complex.*`, `split.*`, and `algebra.quadratic-*` law
families pin only the correctness half, so measure the performance side before
collapsing one.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |