AGENT SKILL

proof-simplify

Use verified TLA+ specs and Lean proofs to simplify real code safely — delete defensive checks the invariants make dead, remove locks/transactions/retries that do no work, collapse redundant states and flags, replace complex implementations with simpler ones proven equivalent, and encode invariants in types — re-verifying every change (re-check, refinement, reachable-state equivalence) before touching code. Use this skill whenever the user asks to simplify, clean up, de-risk a refactor, or reduce complexity in code that has (or could get) a formal model; asks "do we still need this lock / check / retry / state"; wants to turn proofs into code improvements; or finishes a formal-verify bug hunt and wants the payoff. If no verified model exists yet, it starts one via formal-verify first.

License 许可
MIT
最近更新
2026-09-26
Stars
★ 27
Forks
7

01 前言 Front Matter

name
proof-simplify
description
Use verified TLA+ specs and Lean proofs to simplify real code safely — delete defensive checks the invariants make dead, remove locks/transactions/retries that do no work, collapse redundant states and flags, replace complex implementations with simpler ones proven equivalent, and encode invariants in types — re-verifying every change (re-check, refinement, reachable-state equivalence) before touching code. Use this skill whenever the user asks to simplify, clean up, de-risk a refactor, or reduce complexity in code that has (or could get) a formal model; asks "do we still need this lock / check / retry / state"; wants to turn proofs into code improvements; or finishes a formal-verify bug hunt and wants the payoff. If no verified model exists yet, it starts one via formal-verify first.

02 资源文件 8

03 SKILL.md 正文

proof-simplify

A proof tells you what is always true of the system. Code written without that knowledge defends against states that cannot happen: guards that never fail, locks that protect nothing, retries that never fire, flags that duplicate other state. Each piece costs reading time, test time, and latency, and each is a place for new bugs.

This skill turns proven facts into deletions. It proves every deletion safe before making it, then re-verifies afterwards.

The standard of evidence: a simplification is justified only by a property the model proved, under assumptions the code actually enforces. Anything less is a guess dressed up in proof vocabulary.

Preconditions

You need all four of these; without them there is nothing to justify a deletion. If any is missing, run formal-verify (W1) first:

  • a model that passes (TLA+ at stated bounds, or Lean with check_trust.sh clean);
  • frozen properties (Properties.tla / Properties.lean);
  • the model's sanity checks passed (must-fail invariants fail, bug toggles fail);
  • CORRESPONDENCE.md, including its Assumptions list.

Workflow

  1. Harvest candidates. Read the model and the code side by side. Use references/catalog.md for the eight kinds of candidate and how to spot each:

    • a guard implied by the invariant,
    • redundant synchronization,
    • a dead branch or unreachable state,
    • a dead retry or timeout path,
    • a redundant variable or flag,
    • mergeable (bisimilar) states,
    • an implementation replaceable by a simpler proven-equal one,
    • an invariant that can be encoded in types.

    List each candidate with its code location, the model element it maps to, and the fact that would justify it.

  2. Prove each candidate in the model before touching code. Techniques, from cheapest to strongest (references/equivalence.md):

    • Re-check. Apply the simplification to the model, then re-run every frozen property, the sanity checks, and the bug toggles, at the same or larger bounds.
    • Guard implication. In Lean, prove the guard follows from the invariant in every reachable state. In TLA+, check Enabled_A_without_G => G as an invariant.
    • Refinement. Show the simplified spec implements the current one: TLA+ INSTANCE … WITH checked as a PROPERTY, or a Lean simulation theorem. All safety properties then transfer automatically. Liveness must be re-checked.
    • Reachable-state equivalence (Lean reach_iff). The two versions reach exactly the same states. This is the strongest form.
    • Function equality (Lean theorem simple_eq : ∀ x, simple x = current x). Use it for replacing an algorithm.
  3. Audit assumptions. For each candidate, list which Assumptions from CORRESPONDENCE.md the proof relies on, then decide:

    • Remove when every assumption is enforced by code or infrastructure you control (a type, a DB constraint, a single-writer design).
    • Downgrade to an assertion (a debug assert, a metric, or a log-and-continue) when the proof holds but an assumption is only conventional. The next person who breaks the assumption then gets a signal instead of silent corruption.
    • Keep when the code sits on a trust boundary (network input, user input, disk, another team's service, a rolling deploy with mixed versions), or when the assumption is outside your control. Internal invariants never justify deleting validation of external input.
  4. Apply one simplification at a time. For each accepted candidate:

    • make the code change,
    • update the model to match it (the simplified model is now the model),
    • update CORRESPONDENCE.md,
    • run the project's tests and the reproduction tests from earlier findings,
    • re-run the model.

    Use one commit per simplification, whose message names the property that justifies it.

  5. Report. Add simplifications[] to formal/findings.json, then publish the Artifact report (formal-verify/references/report-artifact.md, section "Simplifications"). For each change it shows:

    • the diff,
    • the justifying property or theorem, and its evidence,
    • the assumptions relied on,
    • the decision (removed / downgraded / kept), and
    • the lines-of-code delta.

    Also include the candidates you rejected, with the reason. They are useful knowledge ("the lock looks redundant but protects the cron path, which is not modeled").

Worked examples (both verified)

  • TLA+: a lock that does nothing. assets/tla/CancelOrder.tla models a cancel handler that takes a row lock and uses a conditional UPDATE, while the payment webhook never takes the lock.

    • MC_current.cfg and MC_cas_only.cfg pass.
    • MC_lock_only.cfg fails (exit 13): the lock alone never prevented paid → cancelled.
    • CancelOrderSimple.tla removes the lock, and MC_refines.cfg proves it refines the current spec under a mapping that reconstructs the lock.
    • Mutating the simplified spec to drop the CAS guard makes the check fail, so the refinement check has teeth.

    Decision: remove the lock, keep the CAS, and write the model's finding into the code comment.

  • Lean: a defensive guard the invariant makes dead. lean-model/assets/lean-patterns/ProofPatterns/RedundantGuard.lean:

    • guard_implied: the k ∉ applied re-check follows from the idempotency invariant.
    • reach_iff: with or without it, exactly the same states are reachable.

    Decision: delete it, citing applied_nodup.

Run them:

T=${CLAUDE_SKILL_DIR}/../tlaplus-model/scripts/tlc.sh
for c in MC_current MC_cas_only MC_lock_only; do $T ${CLAUDE_SKILL_DIR}/assets/tla/CancelOrder.tla --config $c.cfg; done
$T ${CLAUDE_SKILL_DIR}/assets/tla/CancelOrderSimple.tla --config MC_refines.cfg

What not to do

  • Don't simplify on the strength of a model that never failed. Sanity checks come first.
  • Don't carry a property from a bounded check into an unbounded claim. "Holds for 2 workers" does not justify deleting a lock that matters at 3. Either argue that the bound covers it (symmetry, or the property is per-pair), prove it in Lean, or re-check at larger bounds.
  • Don't merge several simplifications into one unverified leap. Re-verify after each one. Two individually safe deletions can be jointly unsafe.
  • Don't delete observability (logs, metrics) because a state is "unreachable". Consider turning the branch into an alert.
  • Don't let a refinement proof stand in for liveness. Refinement preserves safety, so re-check liveness separately.

Reference files

  • references/catalog.md — the eight candidate kinds: how to spot them, how to justify them in TLA+ and Lean, and the typical code change.
  • references/equivalence.md — re-check, guard implication, refinement mappings, reachable-state equivalence, and function equality, with verified templates.

04 同仓库更多 Skills

opum-ai
opum-ai/proof-skills

tlaplus-model

TLA+/TLC model-checking skill. Use it whenever TLA+, PlusCal, Quint, Apalache, TLC, a .tla/.cfg file, or model-checker output appears. That includes a pasted TLC error, "Invariant X is violated", or a State 1/State 2… counterexample trace the user wants explained or triaged (real bug, model artifact, or too-strong property), even if it looks answerable by reading alone. Also use it to write, run, scale, or fix specs; debug slow or exploding TLC runs; check invariants, liveness, and fairness; replay production logs against a spec; or "model"/"exhaustively check" concurrent code, protocols, queues, caches, schedulers, leases, retries, and state machines for races, lost updates, double-spends, deadlocks, and ordering bugs, even for a design with no code yet. Not for runtime race detectors, Jepsen, Alloy, Lean/Coq proofs, or UI state-machine libraries. Pair with formal-verify for the full bug-hunt loop.

★ 27
opum-ai
opum-ai/proof-skills

lean-model

Use this skill to prove or refute properties of real software in Lean 4. The target is the user's own code, not textbook math. It covers state machines, concurrency and interleavings, async handlers, retries and idempotency, queues, batching pipelines, and graph algorithms such as topological order, acyclicity and DAG scheduling. Trigger it when the user wants a guarantee for every input or size ("holds for all N"), beyond what TLC, tests or a model checker showed. Also trigger it for invariant proofs by induction, a concrete counterexample trace, an executable reference model for differential testing, or setting up a Lean/lake project to model code. Also use it to audit a Lean development's trust base: sorry, axioms, native_decide. Do NOT use it for pure mathematics such as analysis, algebra or Mathlib coursework and homework. Do NOT use it to translate code into Lean syntax, or for other provers like Dafny, Coq or Isabelle. Pairs with formal-verify for bug hunts and tlaplus-model for protocol exploration.

★ 27
opum-ai
opum-ai/proof-skills

formal-verify

End-to-end formal-methods bug hunting for real codebases in any language — scope a risky concern, model it in TLA+ and/or Lean 4, check it, turn every counterexample into a failing test, fix the code, re-verify, and publish the results as an Artifact report. Use this skill whenever the user wants to find race conditions, lost updates, deadlocks, stale caches, double-applied retries, broken idempotency, message reordering or loss bugs, state-machine violations, dataflow/pipeline loss or duplication, or graph/DAG/scheduler bugs; whenever they say "formally verify", "model check", "prove", "TLA+", "Lean", "invariant", "spec this out", "is this thread-safe", "can this race", or ask for a concurrency/async/distributed review of a module or PR — even if they never name a formal-methods tool. Also the entry point for keeping specs in CI and detecting spec/code drift. Routes to tlaplus-model, lean-model, and proof-simplify for the tool-specific work.

★ 27
opum-ai
opum-ai/proof-skills

quest

Drive this repo's task tracker with the quest CLI instead of editing backlog/tracker state directly. Use whenever creating, listing, viewing, editing, completing, or archiving tasks, drafts, milestones, or decisions in a Quest-initialized workspace. Run `quest instructions --list` for the workflow guides and `quest help [command]` for full usage.

★ 27
opum-ai
opum-ai/proof-skills

lore

Author, retrieve, and maintain OKF documentation with the lore CLI, including explicit multi-repository workspaces. Use whenever reading, writing, linking, moving, querying, or checking docs, so Story/Task coupling, managed blocks, provenance, and cross-links stay coherent. Run `lore instructions` for the canonical agent loop and `lore instructions <topic>` for just-in-time detail.

★ 27