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
- synaptiai/agent-capability-standardtheir own version, first seen Nov 1, 2026
- tamesystems/intent-engineering-skillstheir own version, first seen Oct 20, 2026
- halakou/groundtheir own version, first seen Oct 20, 2026
- ilanbm/kpoppertheir own version, first seen Sep 23, 2026
- envisioning/skillstheir own version, first seen Sep 22, 2026
- reutavidan/zetesis-plugintheir own version, first seen Aug 6, 2026
Other versions8 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 8
- ilanbm/kpopper★ 12same name
- synaptiai/agent-capability-standard★ 7same name
- envisioning/skills★ 2same name
- ahelme/skills★ 1same name
- yiyaw-lab/agent-armor★ 1same name
- halakou/ground★ 0same name
- reutavidan/zetesis-plugin★ 0same name
- tamesystems/intent-engineering-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository6 other files it gives its agents.
- delegated-build-stintSkill
- deneuralyzerSkill
- experiment-freeze-gateSkill
- heartbeatSkill
- literature-scope-disciplineSkill
- seam-proof-buildSkill
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
- Distinctive: line 17
Do not return to the user while any load-bearing claim is UNVERIFIED or any code-determinable fork is unresolved.
- Distinctive: line 35
Read breadth-first - topology: imports, calls, where state lives (graphify query for fan-out questions, else grep/Read).
- Distinctive: line 37
Read the private internals - closures, captured vars, callbacks, indirection - not just exports.
- Distinctive: line 38
Test each plan claim against the code - grep the counts, check the visibility.
- Distinctive: line 40
Write findings into the plan doc.
- Distinctive: line 44
Run the moves, fill the ledger, repeat.
- Distinctive: line 45
Terminate: when a full pass yields no new verifications AND the UNVERIFIED column is empty for all load-bearing claims.
- Distinctive: line 64
When the ledger is clean, spawn the grounding-verifier agent (cold, read-only).
- Distinctive: line 88
One-command behavioral proof: - before/after, a single command the user can run.
- Distinctive: line 95
Default ceiling 2: ground → decide code-determinable forks → implement → verify → stage everything and stop before commit for sign-off.
“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.
Files
/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)
- Read breadth-first - topology: imports, calls, where state lives (graphify query for fan-out questions, else grep/Read).
- Read the private internals - closures, captured vars, callbacks, indirection - not just exports.
- Test each plan claim against the code - grep the counts, check the visibility.
- Name what is intentionally excluded, and why.
- 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:
- The ask - restated in the user's words.
- What I did - plain English, same altitude. ("The turn loop now gets its handle from
for_user(owner)…", not "modified_run_turn:412".) - Decisions + why + rejected alternatives - one line each, plain English.
- Genuine forks for the user, if any.
- 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.
- 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.
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.

