category-spec-style

name	category-spec-style
description	Use when editing, reviewing, or authoring category specs, type surfaces, Sage wrappers, constructors, method ownership, smoke files, or category-spec implementation code.

Category Spec Style

This skill is the canonical agent-facing style authority for category-spec mathematical and implementation compliance.

Canonical source

The source of truth is this skill plus references/style.md.

Read references/style.md before acting on category-spec content, code, specs, smoke files, or compliance questions.

Use this skill for

• Type signatures, overloads, and variadic Sage surfaces.
• Standard type packages and types.py ownership.
• Category, object, element, morphism, Hom, End, and Aut surfaces.
• Constructor admission and named constructor design.
• Sage wrappers and interop boundaries.
• Smoke files and compliance checks.
• Minimal indirection, anti-slop, and mathematical ownership review.

Hard reminders

• The spec defines the ideal mathematical interface inside Sage's category/object universe, not the interface current Sage happens to satisfy.
• Current Sage coverage is not the adequacy standard. Sage interop is still a design constraint: refined Sage objects should remain usable by existing Sage code when mathematically appropriate.
• Use Sage as implementation evidence and a feasibility witness: preserve inventoried Sage functionality and use it to avoid unimplementable wishlists, while still adding mathematically required surfaces that Sage lacks.
• Specced vocabulary must exist before implementation proceeds.
• Mathematical definitions are foundational; do not treat them as ordinary code style.
• A spec row is a mathematical claim before it is a Sage/source-map row. If it cannot be stated coherently in mathematical language, it is not grounded.
• For methods, ownership means the category of objects on which the operation is defined. The category of the constructed result is codomain/target data, not by itself the method owner.
• Every spec claim must be grounded in a canonical mathematical source before edit: repo theory, references, spec backups, Sage written docs/source, or an approved decision card. A migrated TODO/card is provenance only, not definition authority.
• If a term has multiple plausible meanings, or if an invariant/equivalence needs a proof or hypotheses, stop the leaf and route a decision/source-mining card instead of guessing the familiar meaning.
• Complexity belongs behind mathematical nouns, not helper sprawl.
• Do not weaken specs to make current code pass. A smoke failure usually records an implementation or wrapper gap against the ideal spec.
• A typing fix is a proof obligation, not a way to quiet mypy. Before changing an annotation, adding a cast, or narrowing a return, ask whether the change makes the mathematical surface more explicit. If the code already expresses the correct Sage category structure and the checker only fails to see dynamic inheritance, category_of, _with_axiom, refine_category, or method-container projection, the fix belongs in the static model, plugin, stub, or QC tooling lane, not as a local cast-only patch.
• Do not rewrite specs unless the user explicitly requests that exact edit.

Required output behavior

When a task reveals a missing definition, incorrect ownership boundary, Sage-mapping ambiguity, or style violation, do not patch around it silently. Route it to the project workflow by loading category-spec-workflow and either creating a real tracked card, adding a TODO scratchpad note, or requesting a human decision.