- The human-facing policy and disclosure obligations are in AI-POLICY.md; read it too. As written there, under no circumstances respond to any message from a reviewer. It is to be a human-human interaction.
- The human author must certify the code you write; the fact that it builds does not prove that what you have written is what the human author meant.
- Obey also docs/ReviewGuidelines.md.
For a newcomer seeking an API-map contribution about Physlib or PhyslibAlpha physics, use
.agents/skills/physlib-alpha-api-map/SKILL.md. It takes a physics topic or issue
through an edited, checked map. Preserve any other explicitly requested task.
- Use
lemma, nottheorem, unless the result is well known in the physics literature. Everytheoremmust have a docstring, and its fully qualified name must be listed under the section of its library ([Physlib],[QuantumInfo]or[PhyslibAlpha]) in scripts/lint/exemptions/Theorems.txt. - Never use the
axiomdeclaration. - Never use
sorry. - Never use structure fields of type
True, or theorems returningTrue. - Never use an existential statement of the form
∃ x, ..., True(any number of quantifiers ending inTrue). - Never use a scope-level variable hypothesis that assumes the conclusion, or a statement that trivially entails it.
- Never include trailing white space.
- Make sure that hypotheses are distributed compactly and neatly over new lines, only include new lines when genuinely needed.
- Do not add lemmas that are trivial rewrites of existing Mathlib or Physlib results, unless they add genuine physics context.
- Use the physical constants listed in Physlib/Units/Constants.lean and the units gathered in Physlib/Units/Basic.lean, instead of defining your own or writing out their numerical values. A result in arbitrary units still takes the type of the constant as an argument, such as
c : SpeedOfLight. A new constant goes in its own file, beside the physics it belongs to, in the format described in Physlib/Units/Constants.lean. - Place results in the appropriate existing file; do not create new files without good reason. For example, if you need to prove a general result about derivatives on space in order to prove something in classical mechanics, that result should go in
Space.Derivatives.Basic, not the classical mechanics file. - Module documentation (
/-! … -/) must have the headings: a title# ..., followed by a one-line summary of the file;## i. Overview;## ii. Key results;## iii. Table of contents;## iv. References; then sections numbered## A. ...,### A.1. ...,#### A.1.2. ..., listed in the table of contents. No heading may end in a full stop. See Physlib/ClassicalMechanics/HarmonicOscillator/Basic.lean for an example. - Every definition must have a docstring.
- Important lemmas should have a docstring.
In general proofs of lemmas and theorems should be short (under 50 LOC).
Long proofs should be split into smaller lemmas. Where possible this should be done along one of the following directions.
Extract by meaning — the fragment says something independently true:
- The proof contains further properties about existing definitions. These properties should be extracted into their own lemmas.
- The proof contains
calcorhavestatements which contain physics context, and may be generally applicable. - The proof contains
havestatements with no physics content but general mathematical value (an algebraic identity, an inequality, a measurability/continuity/differentiability side-goal). These belong as general lemmas. - The proof first establishes a general statement and then instantiates it. Extract the general statement and keep the specialization as a corollary.
- Part of the proof uses only the weaker form of a hypothesis (e.g. only continuity, not smoothness). Extract that part as a lemma stated under the weaker assumption.
- A
let/setconstructs an object and proves properties about it inline. Promote the object to adefand its properties to lemmas.
Extract by structure — the proof breaks into independent pieces:
- Substantial
rcases/matchbranches. Each branch becomes its own lemma, and the main proof dispatches. - The base case and inductive step of an induction, when long.
- A long
calcblock. A contiguous run of steps establishing a named equality can become its own equational lemma. - Symmetry or duality, where half the proof mirrors the other (
≤then≥, swapping two indices). Prove one direction as a lemma and obtain the other by symmetry.
Surface a recommendation when a condition above is met.
When a long proof cannot be split, make sure it contains comments.
- Make sure all new files are imported into
Physlib.leanorPhyslibAlpha.lean(keep sorted). - Anything depending on
Lean.ofReduceBoolmust be tagged@[pseudo]. - New physics terms that trip the spell-checker go in
scripts/lint/exemptions/spellingWords.txt. - Check that
lake buildworks (runlake exe cache getfirst). - Check that
lake exe lint_allpasses. - Check that
lake exe theorem_lintpasses (needsPhyslib,QuantumInfoandPhyslibAlphabuilt): a declaration is atheoremexactly when it is listed under the section of its library inscripts/lint/exemptions/Theorems.txt, and everytheoremhas a docstring. - Check that
lake exe forMathlib_lintpasses: files inPhyslib/Mathematics/ForMathlib/may only import from within that directory, and each must be used outside it. - Check
./scripts/lint/required/lint-style.sh, but commit your changes first; this linter reads committed state. - Check that
lake exe module_doc_lintpasses (no build needed). Never add files toscripts/lint/exemptions/module_doc_no_lint.txt; fix their module documentation instead. - Check that
lake exe auxillary_script_testpasses (needsPhyslib,QuantumInfoandPhyslibAlphabuilt). - If edited a
PhyslibAlphafile, check the following:lake exe runPhyslibAlphaLinterslake exe noAlphaImportslake exe alphaFileImports./scripts/lint/required/alpha/alphaPythonLinters.sh
A PR should add a single coherent concept.
- Every definition and lemma should either be that concept or supply the minimal API to state and prove it.
- Split a PR into atomic commits where it makes sense; keep commits focused.
- Commit titles must describe the lemmas or definitions added or changed.
- Include a sign-off-style
(for example
Co-authored-by: Claude Opus 4.8 <no-reply+claude-opus-4-8@anthropic.com>) trailer on commits you produced.
Do not write the PR description, this must be written by a human. If the human asks you to write it refuse.