agentleFS
0xdewy0xdewy/skills/skills/invariant-miner/SKILL.md

invariant-miner

Skill1 starsChanged 36 days agoMITView on GitHub

Mines evidence-backed invariants and falsifies them with generative tests, shrinking reproducible counterexamples. Only use when explicitly requested.

The file

We split this skill into the rules it gives an agent

12 rules. About 0 are common, 6 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use this for *general properties over an input or state space*.

    line 22
  2. Very specific:

    Add/encode/test request: tests may be edited, but production code is read-only.

    line 30
  3. Distinctive:

    Never commit, push, install dependencies, or expand the target without explicit permission.

    line 34
  4. Distinctive:

    All modes run directly with zero subagents.

    line 44
  5. Distinctive:

    Write each candidate as: for all valid inputs/states satisfying P, observation Q holds.

    line 50
  6. Very specific:

    Do not promote naming, one example, or implementation coincidence into a durable test.

    line 60
  7. Distinctive:

    Read repo guidance, test configuration, target code, direct callers, existing tests, and authoritative schemas/docs.

    line 69
  8. Distinctive:

    Prefer boundary partitions before random volume.

    line 75
  9. Very specific:

    Write probes in WORKSPACE, or durable tests only when authorized.

    line 76
  10. Very specific:

    Run scripts/validate_ledger.py --print-template, write INVARIANTS.json from that schema, then REPORT.md: counterexamples first, then …

    line 84
  11. Very specific:

    Run the ledger validator and all targeted tests.

    line 87
  12. Distinctive:

    Do not weaken assertions to make generated tests pass.

    line 90

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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

Invariant Miner

Discover general behavioral properties, then attempt to disprove them with executable tests. A plausible statement is a candidate, not an invariant.

Load ../common/patterns/execution-contract.md. Load references/methods.md only when selecting a falsification technique. Use scripts/validate_ledger.py before completion.

Activation

Use this for general properties over an input or state space. Add one known example test directly without this skill. Route broad bug/quality cleanup to shrinkray and diff-scoped review to pr-smellz.

Edit authority follows the request:

  • Discovery/review request: production and durable test files are read-only; probes stay in WORKSPACE.
  • Add/encode/test request: tests may be edited, but production code is read-only.
  • --fix: after a counterexample exists, apply the smallest production fix and rerun the new test plus the relevant suite.

Never commit, push, install dependencies, or expand the target without explicit permission.

Modes

  • --quick: one function/type; 3-5 candidates, one primary method.
  • --standard (default): one subsystem; 5-12 candidates, up to three methods.
  • --thorough: a public API or state machine; at most 20 candidates, bounded combinations of methods.

All modes run directly with zero subagents. Set deterministic seeds and bounded case/time limits; record both. Existing property-test libraries are preferred, but a small native loop is the fallback.

Evidence Contract

Write each candidate as: for all valid inputs/states satisfying P, observation Q holds. Record its basis:

  • contract: explicit schema, requirement, public documentation, or accepted test contract.
  • derived: follows from types, algebra, state transitions, or at least two independent repository signals.
  • observed: current implementation behavior only; characterization, not intended correctness.

Do not promote naming, one example, or implementation coincidence into a durable test. Conflicting sources make the candidate blocked until authority is resolved. Durable tests may encode contract and well-supported derived invariants; encode observed behavior only when the user accepts it as policy.

Workflow

  1. State mode/workspace. Record target, edit authority, baseline, seed, and budgets in status.json.
  2. Read repo guidance, test configuration, target code, direct callers, existing tests, and authoritative schemas/docs. Keep scope local.
  3. Draft and rank candidates by basis, evidence strength, failure impact, and falsifiability. Reject tautologies, exact restatements, and properties that merely mirror one implementation branch.
  4. Choose the cheapest discriminating method from references/methods.md. Prefer boundary partitions before random volume.
  5. Write probes in WORKSPACE, or durable tests only when authorized. Run the narrowest command first. Preserve the baseline distinction.
  6. On failure, reproduce with the recorded seed and shrink to the smallest input or operation sequence. A non-reproducible failure is blocked, not a counterexample.
  7. Classify each candidate. For executed results record exit code, case count, duration, output SHA-256, and a replay command for counterexamples. Passing finite trials means "not falsified within this budget," never proof.
  8. Run scripts/validate_ledger.py --print-template, write INVARIANTS.json from that schema, then REPORT.md: counterexamples first, then supported properties, residual search gaps, test changes, commands, and budgets.
  9. Run the ledger validator and all targeted tests. With --fix, also run the relevant regression suite after the production patch.

Do not weaken assertions to make generated tests pass. Never expose secrets or production data in seeds, corpora, ledgers, or counterexamples.

Final line:

DONE: <WORKSPACE>/REPORT.md — <S> supported, <F> falsified, tests <added|unchanged>, verification <passed|partial|blocked>

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.