grounded

Grounded

Ever typed "look into the scientific evidence on…" and gotten a beautiful, confident answer?

Two things can be wrong with it, and both are invisible:

1. The references don't exist. Papers nobody wrote, DOIs that resolve to nothing, retracted studies quoted as settled fact.
2. The references exist — but don't say that. A real paper, correctly formatted, attached to a claim its authors never made.

You can't catch either without checking every reference by hand. Grounded is an agent skill that does exactly that, so you don't have to.

Grounded builds a narrative literature review from live searches, verified bibliographic records, and source text. Before writing, it records the evidence and its limits in a claims ledger. Afterwards, a separate judge checks the assertions against the sources, including headings, summaries, tables, and captions. A deterministic check verifies quotations and binds the final review to the checked evidence.

The writing develops a connected explanation: each sentence contributes to its paragraph, each section advances the answer, and the narrator reports findings without giving advice. An editorial read checks continuity before figure production and again after factual repairs; source verification alone does not establish writing quality.

The review ships with receipts: the assertion, its sources, the supporting passages, the access level, and the judge’s verdict. A separate assessment explains confidence in each outcome and identifies overlapping studies. Bibliographic identity, quotation support, and scientific certainty are different checks; a passing audit does not make a conclusion infallible.

Traceable sources, independently checked assertions, and explicit evidence limits.

Runs in coding agents with a real shell and network — Claude Code, Codex CLI, and friends. It needs literature API access, Python, artifact storage, and an independent judge context; check actual host capabilities rather than assuming them from its product name. See Requirements.

Grounded is at 0.5.x. The repository includes regression tests and complete example runs; interfaces may still change between minor versions.

Examples

Ask in plain language, naming a size, a style, and an output format — like this:

Use the grounded skill to tell me: what happens to your body when you stop taking Ozempic? Popsci, medium, journal PDF.

Missing dimensions are inferred from context and defaults; Grounded asks only when ambiguity materially changes the task. The examples below use four writing styles and three review sizes.

Each review develops a connected explanation, reports findings without giving advice, and places illustrations and plots beside the evidence they explain. Every assertion was checked independently against its source, and each review comes with its evidence receipts. The masthead of each PDF shows the Grounded version that wrote it.

The examples use as many sources as the question needs. Full-text and abstract-only evidence are distinguished in the receipts; more references do not automatically mean stronger evidence. These familiar examples are development regressions, not held-out validation of the scientific rules.

It can also audit text you already have — an LLM answer, a manuscript section, a press release:

Use the grounded skill to check this draft's claims and references against the literature.

The draft's citations are parsed in common forms (DOI links, [3] with a reference list, (Smith et al., 2020)), every reference is resolved and verified — a reference no index can find is reported as NOT FOUND — and assertions are checked against the available source text, with uncited summaries and factual headings included. You get a scorecard (references: 12 cited · 9 verified · 1 retracted · 2 not found; sentences: 30 cited · 18 supported · 7 partial · 5 unsupported), a line per reference, a receipt per assertion, and the list of citations to fix. Run it on a vanilla model's answer and on Grounded's own review of the same question to compare them on the same terms.

Sizes, styles, formats

Every review has three independent dimensions — combine them freely. The default is medium · popsci · journal PDF.

Size — scope and depth. Reference counts are guidance, not quotas:

Style — how it's written; the rigour never changes:

• scientific — restrained journal prose: abstract, neutral thematic sections, effect sizes, comparison tables, and explicit uncertainty.
• popsci (default) — a magazine-style feature: a few key studies told properly, how the thing works, what it means, every finding cited.
• bullets — TL;DR, informative headings and concise bullets that connect findings.
• ELI5 — everyday language, patient explanation and explicit uncertainty.

Format — how it's delivered:

• inline chat — the review is the reply; every citation is a clickable DOI link, every technical term links to a plain-language explainer, the Sources carry the audit tally, and the receipts file travels alongside.
• journal PDF (default) — journal typesetting with superscript citations and up to 2/5/8 communication-first, style-matched figures for small/medium/large reviews, each doing a distinct evidence job; the colophon states the audit tally (cited sentences, source checks, verdicts by evidence tier) and the receipts file is delivered beside the PDF.
• slides (experimental) — a 16:9 deck of standalone cited slides; the skill never offers it, you have to ask.

Installation

Grounded is a standard Agent Skill — one SKILL.md plus its references/ and scripts/.

Claude Code — install it as a plugin from this repo:

/plugin marketplace add jostelzer/grounded
/plugin install grounded@grounded

Or clone the repo and point ~/.claude/skills/grounded (or a project's .claude/skills/) at its skills/grounded/ directory.

Codex CLI — download grounded.zip from the latest release and unzip it into ~/.agents/skills/ (or a project's .agents/skills/), then start a new session.

Gemini CLI — install it as an extension straight from this repo:

gemini extensions install https://github.com/jostelzer/grounded

Other CLI agents — give the agent the skills/grounded/ folder and use SKILL.md as the operating instructions, keeping references/ and scripts/ alongside.

Requirements

Grounded runs the real pipeline or it does not run. That takes a proper coding environment:

• Outbound network to api.openalex.org, eutils.ncbi.nlm.nih.gov, api.crossref.org, and www.ebi.ac.uk — searching, DOI verification, and the retraction screen all go through them.
• Python 3 with the pinned packages in requirements-pdf.txt, plus WeasyPrint's native Pango libraries for the journal PDF.
• A writable filesystem for the working ledger each review builds.

Check these capabilities in the actual host before starting. If literature APIs, artifact storage, or an independent judge context are unavailable, report that limitation instead of presenting an unverified review as verified. The .skill and .zip bundles are published for environments that meet the requirements above.

Under the hood

The model does the reading and writing; deterministic scripts do the searching, verification, and rendering. One pipeline, every time:

1. Scope — the question is split into the angles a thorough reviewer would cover: existing reviews, largest primary studies, mechanism, contrary and null findings, harms, populations, recent work.
2. Search — find_papers.py cursor-pages OpenAlex and offset-pages PubMed angle by angle, writing every query to an auditable search manifest; central papers get citation-chased in both directions. Preprints are excluded at the gate.
3. Read — every abstract that might be cited; open-access full texts (Europe PMC) for the load-bearing papers, behind an authenticity audit that rejects paywall stubs and challenge pages.
4. Verify — verify_citations.py checks every DOI against Crossref: title, year, article type, and integrity status — retractions, withdrawals, removals, and expressions of concern via publisher and Retraction Watch update metadata. A failure is a hard stop: the source is fixed or dropped before a word is written. A thin source list on a fringe topic is the skill working, not failing.
5. Synthesize, write & validate — the verified evidence is first distilled into a style-neutral claims ledger (every claim with its strength, exact numbers, contrary evidence, boundaries, and a verbatim quote from every source it cites, string-checked before drafting); the styled review is then composed from those claims, citing ledger keys, never remembered references, and never a source the ledger did not quote. Citations and the reference list are generated from the verified records, and a deterministic validator checks structure, citation placement, DOI parity, and figure contracts before delivery. For popular science, the article is one continuous story built on a handful of studies, each told as a small story with how it was actually run. Before searching, the questions a curious non-specialist would ask are written down, and a background search finds what answers them: definitions, mechanisms, everyday scale, a yardstick for the numbers. A writer with a clear desk and the stored sources drafts the piece; exact figures go into a table after the ending. A readability profile points at overloaded or choppy passages, and two cold readers who see only the article say where they stumbled before one revision.
6. Explain visually, then render — every figure first states what the reader should understand, where familiar intuition begins, the eye path that builds the idea, and the one sentence a non-specialist should be able to explain back. Non-quantitative figures compare three detailed concepts for clarity, simplicity, completeness, elegance, and intuitiveness; only the winner reaches the image generator. In-pixel copy stays short, distinct sections use uppercase A–D in every writing style, and explanatory callouts point to exact targets when useful. Numerical comparisons use source-verified deterministic plots, with equal typography for comparable quantities across panels. Each review plans a meaningful illustration–plot mix; an illustration explains a study, mechanism, or evidence boundary rather than decorating the data. After rendering, the agent states what the pixels actually communicate and must revise when the image requires its caption, leaves jargon unexplained, or fails the explain-back test. The journal PDF is typeset with pinned WeasyPrint, then QA independently proves figures and fonts were not stretched and re-rasterizes every page with Poppler.
7. Audit and receipt — inventory all assertions, including headings and uncited summaries. A fresh judge qualifies against unlabelled multi-domain cases, then checks source quotations, quantities, qualifications, and element coverage against the relevant methods, results, table headers and notes. New audits record the claim’s scientific meaning, inspected source ranges and interpretation separately from quote matching and evidence strength. A final whole-review check examines the reader’s takeaway and each rendered figure against checked scientific claims. Changes to source context, judgments, prose or figure files invalidate the applicable approvals. Partial source support is accepted only when other evidence covers the remaining elements. Receipts distinguish attribution, interpretation, source access and outcome certainty; historical audits are not relabelled as having passed the new checks. Deterministic checks establish consistency, not scientific truth or judge independence.

License

MIT

Verification contract

Written reviews use schema-v2 assertion audits: exact review/evidence binding, complete element coverage, independent classification of uncited material, and a multi-domain judge qualification set. Outcome certainty and study-family overlap are assessed separately from quotation support. Source counts are advisory; contrary searches are required but disagreement is not. A compact methods disclosure reports scope and access limitations. Canonical budgets live in skills/grounded/scripts/review_config.py and generate the budget table and evaluation metadata. Document-local statements about searches, source access, and figure geometry are independently checked against the actual run artifacts, whose file hashes are bound into the audit. Scientific claims still require source support; local artifacts cannot substitute for scientific evidence.