AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

writing-lean-proofs

Writes and reviews structured Lean 4 proofs and designs Lean libraries following Mathlib conventions. Use when proving theorems in Lean, formalizing mathematics or specifications in Lean 4, defining new types or definitions in a Lean library, reviewing Lean proofs for readability and maintainability, refactoring long tactic proofs into lemmas, filling in sorry placeholders in a Lean development, setting up CI or linters for a Lean project, diagnosing slow proofs or maxHeartbeats timeouts, or writing custom tactics, macros, or linters.

Original source
trailofbits
License
CC-BY-SA-4.0
Pinned revision
2be6433b39e009cd2b6fd3be1895f6b1faa5af9a

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read trailofbits--writing-lean-proofs at revision 2be6433b39e009cd2b6fd3be1895f6b1faa5af9a, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 9

references/anti-patterns.md

Anti-patterns

Each entry: what it is, why it is harmful (not just that it is), and which mechanism catches it. The meta-lesson from Mathlib's history: review alone does not catch these — the first simp-normal-form linter found over one hundred redundant simp lemmas that had all passed expert maintainer review. Put the check in tooling.

Proof-level

Monolithic tactic blocks

One long unstructured tactic sequence. Harmful because the argument's structure is invisible — the only way to follow it is to replay it in an editor, and the only way to repair it after a library bump is to rebuild it from scratch. Caught by: review ("long and unwieldy" → split). Fix: sorry skeleton first, extraction ladder after.

Unfocused multiple goals

Running tactics while several goals are active, relying on goal order. Harmful because any change to an earlier tactic silently redirects later tactics to different goals. Caught by: multiGoal linter. Fix: · blocks, one per goal.

Squeezed terminal simp

simp only [thirty, lemmas, ...] closing a goal. Harmful because it breaks on any rename among the thirty and hides the one lemma that mattered. Terminal simp calls stay unsqueezed; only non-terminal calls get squeezed (a bare non-terminal simp is the mirror-image anti-pattern: it couples following tactics to the ambient simp set). Caught by: review; the style guide states the rule.

Dishonest show

show that actually changes the goal. Harmful because readers trust show lines as documentation of the goal state; a goal-changing one is documentation that lies. Caught by: show linter. Fix: change.

native_decide in library code

Proves a proposition by compiling it to native code and trusting the result (the Lean.ofReduceBool axiom). Harmful because it silently widens the trust base from the kernel to the entire compiler and runtime; Mathlib disallows it. Caught by: #print axioms (reports Lean.ofReduceBool); Mathlib CI. Fix: decide where the kernel can afford the computation, a certificate-based norm_num proof, or an explicitly documented decision to accept the axiom.

Leftover debugging scaffolding

set_option pp.all true, trace/profiler/debug options, unscoped maxHeartbeats. Harmful as noise and as behavioral drift (heartbeat overrides mask performance regressions). Caught by: setOption linter.

Golfed nontrivial proofs

Compressing a real argument into a one-liner of chained combinators. Harmful because review policy subordinates golfing to readability — the short form is only acceptable when it reads at least as well. Trivial results are the carve-out. Caught by: review.

Non-canonical statements

Stating with > instead of <, or against a concrete spelling instead of the designated simp-normal form. Harmful because simp and every API lemma match syntactically — off-normal statements need duplicate API or never get rewritten. Caught by: simpNF linter (for simp lemmas); review. The numeral special case is easy to miss: a simp lemma keyed on 2 ^ 32 never fires on a goal normalized to 4294967296 — the lemma is true, applicable-looking, and dead. Prefer structural LHS patterns with no numeral at all.

Copy-pasted resource budgets

The same set_option maxHeartbeats N in value on many declarations. Harmful because at that density the annotations carry no information about which proof is actually expensive, and every unmeasured budget masks the regression it was meant to surface — audits have found "6.4M-heartbeat" proofs that run at the default budget once measured. Caught by: #count_heartbeats bisection; Mathlib's maxHeartbeats style linter (which demands a justification comment on every override — the unscoped file-level form is the setOption linter's, see "Leftover debugging scaffolding" above). Fix: measure, keep only the overrides that are real, each scoped to its declaration.

Library-level

Project conventions enforced only by review

A project-specific construct — a simp-set discipline, a required attribute, a coverage rule like "every constructor the executor handles has a soundness lemma" — with no linter behind it. Harmful because the failure mode is forgetting the step on 1 of 30 declarations with no visible symptom, which is precisely what review does not catch (and what models writing Lean get wrong). Caught by: nothing — that is the problem. Fix: a declaration-level @[env_linter] wired into CI's #lint, written alongside the construct, not after the first regression. See linting.md.

Definitional transparency abuse

Downstream proofs that unfold, use erw, or need a trailing rfl to see through a definition. Harmful because each one couples a proof to the implementation; the first refactor breaks them all. The style guide calls this missing API. Caught by: review; the erw/trailing-rfl smell. Fix: add the missing lemma next to the definition.

Definitions without API

A definition used bare, with lemmas about it scattered where they were first needed. Harmful because every user re-derives basic facts, usually by unfolding (see above). Caught by: PR review checklist ("do new definitions come with lemmas about them?"). Fix: same-file ext/simp/coe/injectivity lemmas before first use.

Unbundled predicates for morphisms/subobjects

IsHom f predicates instead of a bundled Hom structure with FunLike. Harmful because instance search cannot reliably discharge IsHom (f ∘ g), and the predicate form forfeits the algebraic structure of the hom-type itself. Caught by: review guide (directs to FunLike/SetLike).

Side conditions instead of junk values

Partial operations via subtypes or hypotheses on the operation rather than junk-value totalization. Harmful because the side condition reappears at every use site ("every step slightly painful" — perfectoid retrospective on the subtype approach). Fix: total function + junk value; hypotheses only on the lemmas that need them.

Global Fact instances

instance : Fact (Nat.Prime 37) at top level. Harmful because every typeclass search everywhere now considers it. Fix: state as lemma, make a local instance where needed.

Premature typeclasses

A new class with no theory behind it. The bar: real mathematics to be done with it, or genuine simplification from a factored substructure. Prefer extends to mixin parameters.

Claims to avoid making

When editing or reviewing, do not cite these as rules — they are commonly repeated but unsupported or wrong:

  • "One tactic per line is an absolute requirement" — Mathlib recommends one tactic invocation per line in general, but explicitly excepts a proof that closes the goal and fits entirely on one line. Apply the recommendation with that exception instead of inventing a hard rule.
  • Any numeric proof-length threshold ("proofs over 20 lines must be split") — the review criterion is deliberately qualitative.