← Back to Systems

Mathematical Autopsy (MA)

Mathematical Autopsy is a generic template for mathematically rigorous development with a doc-first approach, notebook validation, and CI enforcement. The MA process ensures documentation defines guarantees before code, notebooks generate JSON artifacts proving invariants, and CI gates prevent drift. Every system follows this methodology: Docs/spec → Math → Lemmas/proofs → Invariants → Notebooks → Code → Tests & CI gates, ensuring mathematical rigor and traceability across all development.

Mathematical Autopsy

MA

Mathematical Autopsy is a doc-first, determinism-driven methodology that transforms software development from ad-hoc implementation to mathematically verified systems. Every system starts with formal documentation that defines guarantees before any code is written, and CI gates enforce these mathematical guarantees throughout the development lifecycle.

MA Process (Canonical)

  1. Docs/spec: North Star + Execution Plan set scope and contracts (normative)
  2. Math: Formalize the calculus; define assumptions and goals
  3. Lemmas/proofs: Record rationale and bounds; link back to code lines
  4. Invariants: Encode guarantees in `invariants/INV-XXXX.yaml` (what must be true)
  5. Notebooks: Produce JSON artifacts proving the invariants (seeded; no NaN/Inf)
  6. Code: Implement exactly what the docs/math specify; no drift
  7. Tests & CI gates: Enforce invariants, API contract, determinism, lint/format, SBOM, secret scan

Methodology: MA Doc-First

  • Docs are normative: North Star and math appendices define guarantees. Code must implement the documented math.
  • Notebooks are producers: Math notebooks generate JSON artifacts under `configs/generated/` that encode thresholds, normalizations, and proofs.
  • CI gates enforce math: Validation runs notebooks, checks artifact freshness and No-NaN/Inf, and evaluates invariants to a single scorecard decision.
  • Code merges only after gates are green: If docs or artifacts drift/stale, CI blocks promotion.

Key Components

  • Invariant Template: Standard format for mathematical guarantees
  • Notebook Template: Standard structure for verification notebooks
  • Artifact Schema: JSON artifacts encoding thresholds, bounds, and proofs
  • CI Gate Scripts: Automated validation and enforcement
  • Scorecard System: Single green/yellow/red decision

For detailed technical documentation, see the MathematicalAutopsy repository documentation.