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
- 资产文件assets/tla/CancelOrder.tla2.0 KB
- 资产文件assets/tla/CancelOrderSimple.tla1.6 KB
- 资产文件assets/tla/MC_cas_only.cfg131 B
- 资产文件assets/tla/MC_current.cfg130 B
- 资产文件assets/tla/MC_lock_only.cfg114 B
- 资产文件assets/tla/MC_refines.cfg91 B
- 参考文档references/catalog.md5.8 KB
- 参考文档references/equivalence.md3.5 KB
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.shclean); - 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
-
Harvest candidates. Read the model and the code side by side. Use
references/catalog.mdfor 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.
-
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 => Gas an invariant. - Refinement. Show the simplified spec implements the current one: TLA+
INSTANCE … WITHchecked 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.
-
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.
-
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.
-
Report. Add
simplifications[]toformal/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.tlamodels a cancel handler that takes a row lock and uses a conditional UPDATE, while the payment webhook never takes the lock.MC_current.cfgandMC_cas_only.cfgpass.MC_lock_only.cfgfails (exit 13): the lock alone never preventedpaid → cancelled.CancelOrderSimple.tlaremoves the lock, andMC_refines.cfgproves 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: thek ∉ appliedre-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
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.
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.
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.
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.
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.