agentleFS
BarzinLBarzinL/barzins-cc-improvements/ground-skill-verifier/SKILL.md

ground

Skill2 starsChanged 4 months agoMITView on GitHub

Self-terminating grounding loop for a development step. Turns assertions, assumptions, and inferences into verified knowledge via an evidence-backed ledger; self-resolves code-determinable forks and logs them; escalates only genuine preference forks; spawns an independent verifier; and emits a plain-English review packet at the user's altitude. Invoke before implementing any non-trivial step, or whenever asked to "ground" something.

8 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

10 rules. 0 are common, 10 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 8 edited versions we read keep these.

  • 10

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Do not return to the user while any load-bearing claim is UNVERIFIED or any code-determinable fork is unresolved.

    line 17
  2. Distinctive:

    Read breadth-first - topology: imports, calls, where state lives (graphify query for fan-out questions, else grep/Read).

    line 35
  3. Distinctive:

    Read the private internals - closures, captured vars, callbacks, indirection - not just exports.

    line 37
  4. Distinctive:

    Test each plan claim against the code - grep the counts, check the visibility.

    line 38
  5. Distinctive:

    Write findings into the plan doc.

    line 40
  6. Distinctive:

    Run the moves, fill the ledger, repeat.

    line 44
  7. Distinctive:

    Terminate: when a full pass yields no new verifications AND the UNVERIFIED column is empty for all load-bearing claims.

    line 45
  8. Distinctive:

    When the ledger is clean, spawn the grounding-verifier agent (cold, read-only).

    line 64
  9. Distinctive:

    One-command behavioral proof: - before/after, a single command the user can run.

    line 88
  10. Distinctive:

    Default ceiling 2: ground → decide code-determinable forks → implement → verify → stage everything and stop before commit for sign-off.

    line 95

“Common” is measured: kept by at least 6 in 10 of the 8 edited versions of this file we could read. “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

/ground - executable grounding protocol

Operationalizes the pre-implementation grounding pass in CLAUDE.md and docs/research/coding/pre-implementation-grounding.md. That protocol is correct but aspirational - it relies on the operator re-prompting "ground further" 2–4× per step. This skill makes it self-terminating (a ledger with a termination test), self-resolving (a decision policy for forks), and independently verified (a cold second agent), so it runs to completion without re-prompting.

Core invariant

Do not return to the user while any load-bearing claim is UNVERIFIED or any code-determinable fork is unresolved. "Looks done" is not a termination criterion - an empty UNVERIFIED column is.

1. Build the ledger

List every claim the step rests on, as a table: | # | Claim | Status | Evidence |

  • A row is VERIFIED only when Evidence is a concrete file:line (read) or a command + its output (run).
  • "Structurally certain" / "by reading" / "likely" / "should" → UNVERIFIED. No exceptions.
  • Behavioral claims - control flow, ordering, teardown, exception propagation, state mutation, concurrency - require run evidence, not read evidence. Reason only to design the check; then run it.
  • A claim too vague to mark either way is split into checkable sub-claims.

2. The five moves (from CLAUDE.md)

  1. Read breadth-first - topology: imports, calls, where state lives (graphify query for fan-out questions, else grep/Read).
  2. Read the private internals - closures, captured vars, callbacks, indirection - not just exports.
  3. Test each plan claim against the code - grep the counts, check the visibility.
  4. Name what is intentionally excluded, and why.
  5. Write findings into the plan doc.

3. The loop + termination

Run the moves, fill the ledger, repeat. Each pass must verify ≥1 row or split a vague claim. Terminate when a full pass yields no new verifications AND the UNVERIFIED column is empty for all load-bearing claims. This is the "2–4 passes" - now self-driven.

4. Decision policy - make forks resolve themselves

For each fork the grounding surfaces, classify:

  • Code-determinable - one branch is correct given how the code wires, a project invariant, or the development trajectory. → Decide it. Write decision + grounded reasoning + rejected alternative(s) into the plan doc's decision log. Do not ask.
  • Preference / value - needs the user's priorities, risk tolerance, or product direction; or is irreversible and expensive. → Stop and surface it inline (markdown list, never AskUserQuestion) with a grounded recommendation.
  • Unsure which class → treat as preference and surface. Conservative on purpose.

The bar: ask only what the code genuinely cannot answer.

5. Independent verification

When the ledger is clean, spawn the grounding-verifier agent (cold, read-only). Give it the step goal + the ledger + the diff (if any) - not your justification narrative. It performs:

  • (a) Row-check - each cited evidence actually supports its claim; re-run behavioral checks (the run is ground truth regardless of reader).
  • (b) Gap-scan - independently hunt load-bearing claims the ledger omits: bypass paths, untested assumptions, unnamed exclusions, count claims that are off. For high-stakes steps it builds its own ledger and diffs against yours.
  • (c) Summary-fidelity - confirm the §6 packet faithfully describes the diff.

Resolve every REFUTED / INSUFFICIENT finding (re-ground, fix, or escalate) before surfacing. The verifier reduces but does not eliminate error - it breaks the self-grading loop. Independence comes from cold context + adversarial stance, not model diversity (same model is fine).

6. The review packet - abstraction parity

The ledger is an audit trail, not a review surface. Produce a separate packet at the altitude of the user's original request, descending to code only in an appendix:

  1. The ask - restated in the user's words.
  2. What I did - plain English, same altitude. ("The turn loop now gets its handle from for_user(owner)…", not "modified _run_turn:412".)
  3. Decisions + why + rejected alternatives - one line each, plain English.
  4. Genuine forks for the user, if any.
  5. One-command behavioral proof - before/after, a single command the user can run. Every load-bearing behavioral claim in the prose cites a runnable check, so the summary is anchored to ground truth, not floating prose.
  6. Appendix - ledger, decision log, full diff. There for drill-down, never required to review.

7. Ceiling (autonomy)

Default ceiling 2: ground → decide code-determinable forks → implement → verify → stage everything and stop before commit for sign-off. Ceiling 1: also commit autonomously (move here once the decision log shows self-resolved forks landing where the user would). Ceiling 3: widen the preference class, escalate more.

Anti-patterns (hard stops)

  • Marking a behavioral claim VERIFIED from reading. Run it.
  • Bouncing a code-determinable fork to the user because asking is cheap.
  • Treating the ledger as the review surface (forces the user to learn the codebase to review).
  • Reactively patching when a check fails - read the code and reason first (see stopping-rules/ §2).
  • Surfacing before the verifier has cleared its findings.

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.