fv-docs
Skill61 starsChanged 6 months agoApache-2.0View on GitHub
Explicitly invoked only. Authoritative reference for the Ragu formal-verification project — Clean DSL semantics (Circuit monad, Expression, Operation, ProvableType, FormalCircuit) and Ragu-side concepts (extraction driver, formal instances, input/output serialization, assumptions, CI). Routes to the live in-tree FV docs; the docs are the spec, not opinion. Pair with /fv-review for opinion / pattern-matching guidance. Invoke when the user types `/fv-docs` or asks for the canonical definition of a Clean / Ragu-FV concept.
In this repository15 other files it gives its agents.
- alex-reviewSkill
- book-fixmeSkill
- book-refineSkill
- book-reviewSkill
- clean-circuitsSkill
- code-refineSkill
- code-reviewSkill
- doc-auditSkill
- fv-preflightSkill
- fv-reviewSkill
- help-book-reviewSkill
- master-fvSkill
- sean-reviewSkill
- spec-fidelity-auditSkill
- tal-reviewSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 71
If the question names a term from the Term → file table → Read that file from the live <docs> root.
- Distinctive: line 72
If the question matches a topic but no specific term → consult Topic → file for the right doc.
- Distinctive: line 73
If neither matches → the answer probably isn't in this corpus.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
fv-docs: Ragu Formal Verification reference
The FV documentation lives in the repo. This skill is a routing layer: pick the right doc and Read it from the live source — don't paraphrase. The docs are authoritative; they define what FormalCircuit, formal instances, ExtractionDriver, etc. mean.
Pairing. For definitions → fv-docs (this skill). For opinion / pitfalls / pattern-matching (e.g., "should I use FormalCircuit or GeneralFormalCircuit?", "what's a clean spec style?") → /fv-review. Don't compete on the same question.
Where the docs live
The FV docs are Part IV of the Ragu book, rooted at book/src/fv/. Treat <docs> below as that path.
Older checkouts predate the merge into the book and have the docs as a standalone mdBook at qa/lean/docs/src/ (or, earlier still, fv/docs/src/), with clean/core/ in place of clean/, ragu/ in place of circuits/, and introduction.md in place of index.md. If unsure, ls book/src/fv/ 2>/dev/null || ls qa/fv/docs/src/ resolves it.
Topic → file (what each doc answers)
Clean DSL:
<docs>/clean/index.md— what Clean is; soundness vs completeness as concepts; compositionality.<docs>/clean/circuit.md— theCircuitmonad:ℕ → α × List (Operation F),bindsemantics, witness offset threading.<docs>/clean/mul.md— minimal worked example: a multiplication circuit walked end-to-end.<docs>/clean/provable.md—TypeMap,ProvableType,ProvableStruct; structured values vs symbolic forms;field,Var.<docs>/clean/expression.md—Variable,Expression,ProverEnvironment; how symbolic circuits are evaluated.<docs>/clean/operations.md—FlatOperationvsOperation; witness / assert / lookup; why operations are the ground truth.<docs>/clean/formal.md— the formal-circuit bundle family (FormalCircuit,FormalAssertion,GeneralFormalCircuit,GeneralFormalCircuit.WithHint); the prover/verifier precondition split (Assumptions,ProverAssumptions,ProverSpec,ProverData,ProverHint); structure ofmain/Assumptions/Spec/soundness/completenessfields; the formal definitions of soundness and completeness.<docs>/clean/example.md— full worked example tying circuit + provable + expression + formal together (DivNonzero).<docs>/clean/parameters.md— compile-time parameters as ordinary Lean function arguments; partial-application instantiation.
Ragu FV pipeline:
<docs>/circuits/index.md— the two-approach analysis (high-level export vs. low-level trace); why Ragu chose the low-level export with a Lean reimplementation; the formal instance interface and its fields.<docs>/circuits/extraction.md—ExtractionDriver,MaybeKind = Empty,ImplWire = Expr<F>; howalloc/mul/add/enforce_zero/constantmap to operations.<docs>/circuits/serialization.md— symbolic input wires,input_var.get i,alloc_input_wires,serializeOutput/deserializeInput.<docs>/circuits/fingerprint.md— the vk-style fingerprint equivalence check (the sole Rust↔Lean tie since the autogen trace files andsame_constraintsproofs were removed): canonical byte encoding + SHA-256 digest of the op trace, computed in both the Rust extractor (lean_extraction -- fingerprint) and Lean (lake exe fingerprints), compared in CI; the2³²input-variable index region; trust assumptions of the check.<docs>/circuits/assumptions.md— what the FV does and does not guarantee; trusted core; axiom dependencies (propext,Classical.choice,Quot.sound,Lean.ofReduceBool,Lean.trustCompiler,Ragu.Core.Primes.p_prime).<docs>/circuits/ci.md—cargo run -p lean_extraction -- check,lake build --wfail(sorry-as-failure) over every module underqa/fv/Ragu/via the lib glob, so an unimported file cannot escape; fingerprint comparison step.
The book TOC lives at book/src/SUMMARY.md if you want the canonical reading order.
Term → file (use for definition lookups)
| Term | Defined in |
Circuit (monad), bind, witness offset | clean/circuit.md |
Variable, Expression, ProverEnvironment | clean/expression.md |
Operation, FlatOperation, witness, assert, lookup | clean/operations.md |
TypeMap, ProvableType, ProvableStruct, field, Var | clean/provable.md |
FormalCircuit, FormalAssertion, GeneralFormalCircuit, GeneralFormalCircuit.WithHint, .toWithHint, Assumptions, ProverAssumptions, Spec, ProverSpec, ProverData, ProverHint, soundness, completeness (formal definitions) | clean/formal.md |
| Compile-time parameters, partial-application instantiation | clean/parameters.md |
FormalInstance, reimplementation | circuits/index.md |
same_constraints, same_output, exportedOperations, exportedOutput (removed; superseded by the fingerprint check) | circuits/fingerprint.md |
ExtractionDriver, MaybeKind, ImplWire, driver-method → op-trace mapping | circuits/extraction.md |
input_var.get, alloc_input_wires, serializeOutput, deserializeInput | circuits/serialization.md |
Fingerprint, canonical encoding, lean_extraction -- fingerprint, lake exe fingerprints, Ragu.Fingerprint, inputVarOffset | circuits/fingerprint.md |
| Trust assumptions, axiom dependencies | circuits/assumptions.md |
--wfail, lean_extraction -- check, what CI verifies | circuits/ci.md |
Reading order (for new readers)
<docs>/index (scope, what is and is not verified) → clean/index → clean/circuit → clean/provable → clean/expression → clean/operations → clean/formal → clean/mul → clean/example → clean/parameters → circuits/index → circuits/extraction → circuits/serialization → circuits/fingerprint → circuits/assumptions → circuits/ci.
Out of scope
- Lean syntax basics, tactic strategy, mathlib usage — not in this corpus; consult Lean / mathlib docs.
- Specific gadget proof bodies (e.g., the body of
Point.AddIncomplete.soundness) — read source underqa/fv/Ragu/Circuits/.... - Opinion on circuit-type choice, naming conventions, spec style, "did the spec lift to high-level operations" — that's
/fv-review.
Routing rule of thumb
- If the question names a term from the Term → file table →
Readthat file from the live<docs>root. - If the question matches a topic but no specific term → consult Topic → file for the right doc.
- If neither matches → the answer probably isn't in this corpus; say so rather than guess.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

