agentleFS
tachyon-zcashtachyon-zcash/ragu/.claude/skills/fv-docs/SKILL.md

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.

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
  1. Very specific:

    If the question names a term from the Term → file table → Read that file from the live <docs> root.

    line 71
  2. Distinctive:

    If the question matches a topic but no specific term → consult Topic → file for the right doc.

    line 72
  3. Distinctive:

    If neither matches → the answer probably isn't in this corpus.

    line 73

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 — the Circuit monad: ℕ → α × List (Operation F), bind semantics, 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 — FlatOperation vs Operation; 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 of main / Assumptions / Spec / soundness / completeness fields; 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>; how alloc / mul / add / enforce_zero / constant map 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 and same_constraints proofs 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; the 2³² 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 under qa/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)

TermDefined in
Circuit (monad), bind, witness offsetclean/circuit.md
Variable, Expression, ProverEnvironmentclean/expression.md
Operation, FlatOperation, witness, assert, lookupclean/operations.md
TypeMap, ProvableType, ProvableStruct, field, Varclean/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 instantiationclean/parameters.md
FormalInstance, reimplementationcircuits/index.md
same_constraints, same_output, exportedOperations, exportedOutput (removed; superseded by the fingerprint check)circuits/fingerprint.md
ExtractionDriver, MaybeKind, ImplWire, driver-method → op-trace mappingcircuits/extraction.md
input_var.get, alloc_input_wires, serializeOutput, deserializeInputcircuits/serialization.md
Fingerprint, canonical encoding, lean_extraction -- fingerprint, lake exe fingerprints, Ragu.Fingerprint, inputVarOffsetcircuits/fingerprint.md
Trust assumptions, axiom dependenciescircuits/assumptions.md
--wfail, lean_extraction -- check, what CI verifiescircuits/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 under qa/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

  1. If the question names a term from the Term → file table → Read that file from the live <docs> root.
  2. If the question matches a topic but no specific term → consult Topic → file for the right doc.
  3. If neither matches → the answer probably isn't in this corpus; say so rather than guess.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.