ByteTerrace/Puck / .claude/skills/maths-laws
maths-laws
VerifiedAuthors Puck.Maths.Tests laws: laws/*.json rows, LawRegistry bindings, oracles, legs, waivers, structural law completeness. Primitive choice: maths-usage.
Writing a Puck.Maths law that bites
During the refactoring campaign, AGENTS.md suspends blanket coverage, testing and gate requirements. Follow an explicit brief's verification, and write laws for exact properties that running cannot show. The declaration/binding workflow below keeps any laws a change does add structurally complete.
This skill owns authoring and validating tests/Puck.Maths.Tests. The suite's
code and tests are authoritative; reconcile its README, XML documentation and
this skill with them when they disagree.
What a law is for
AGENTS.md sets the owner's target for the suite, suspended during the
campaign: the smallest set of tests that reaches 100% line coverage, plus a
short keep-list of invariant tests that coverage cannot see (determinism, exact
fixed-point results). That shapes every decision here.
- Write a law where running the change cannot show the behavior: an exact fixed-point result, a refusal or overflow boundary, a determinism property. A new public member is classified by a law or a precise waiver when the change needs one.
- Author at the
Defaulttier. A Deep row that only draws more random operands from its Default sibling's domain adds no evidence and no line coverage; write one only for a domain Default cannot reach (the exhaustive edge cross product, a whole finite carrier, a longer ladder), and delete a mirror you touch that does not. - The owner's ruling deletes the Maths coverage ratchet, its floor, all recorded registers and their generator. Keep structural declaration/binding completeness and member-reference checks against current LawRegistry data; write no recorded artifact.
Required workflow
- Declare a law in two places and nowhere else: the declaration (id, tier,
covered members, legs) as a JSON row in
tests/Puck.Maths.Tests/laws/<family>.json, and one binding inLawRegistry.csor its per-family partial (ClaimCase,SweptCase, orCase(id, run)for any other run). A bare[Fact]runs but credits no member to the structural completeness check and declares no leg. A declaration without a binding, or a binding without a declaration, failsLawDeclarationTests.EveryDeclarationHasExactlyOneCaseby name. - Choose the cheapest honest tier by measured cost, not by whether the word
"exhaustive" fits.
Exhaustiveholds full-carrier sweeps and expensive finite checks, which take their own basis rather than aDomainand never imply a full-carrier proof. - State the claim, subject, operand domain and evidence legs explicitly.
- Instantiate the existing
Laws.cscombinators and shared domains instead of re-implementing their loops. - Give the claim independent evidence. A second expression of the same
implementation is not an oracle: reference arithmetic lives in
Oracles.cs, computed inBigInteger, and never calls aPuck.Mathskernel. - Classify every affected public Maths member with a covering law (
Membersin its declaration) or a precise waiver (Coverage.WaiverDeclarations).LawCompletenessTestsvalidates those references and waiver reasons without a baseline; declaration/binding parity lives inLawDeclarationTests. - When it is in doubt whether a new law can fail, apply a plausible one-line
mutation in a worktree of your own and watch the law go red, or run
puck laws prove <law> --fix <commit>(--file-listfor an uncommitted fix). Most laws are rows of one theory, whichpuck laws provecannot select one at a time; prove such a row with an exact mutation, failing at the intended assertion, and name the mutation in the commit. Never hand-revert files in a shared tree.
Deleting a law removes its JSON row, binding and any oracle only it used. Every run uses the same deterministic operand window; no counter is persisted.
Run a tier
Build the test project with -nodeReuse:false, then run it:
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
-nodeReuse:false belongs to the build step only
(verification). The plain run is the
Default tier and includes the completeness and leg checks,
which only a run that includes the Default tier checks. Deep and Exhaustive
cases are explicit:
--explicit on --filter-trait tier=<tier>, and without --explicit on such a
filter selects no test. One law runs with
--explicit on --filter-display-name '<law-id>*'; the trailing wildcard is
required.
Load the full reference selectively
Read references/complete-reference.md for
the exact Case shape and combinators, tier budgets, the leg taxonomy and its
markers (ENVELOPE:, OWED:, MIRROR of, DOC GAP:), oracle standards,
domain construction, coverage categories and waivers, claim-body rules, the
mutation procedure and deliberate-correction rules.
Route adjacent work
| Skill | Use when |
|---|---|
maths-usage | Selecting a Maths primitive, applying consumer determinism rules, or deciding which verification tier an implementation change owes. |
content-search | Finding law ids, declarations, member names or textual patterns across the suite. |
symbol-analysis | Resolving semantic C# references, overloads, implementers or rename and deletion safety. |
gaming-bricks | Verifying a Maths change that reaches emulator code and its dedicated batteries. |
verification | The landing bar, optional checks beyond the law suite, and the CLI copy. |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |