| name | base-in-reality |
| description | Research-grounded, read-only audit that validates a repository's codebase, architecture, and business logic against real-world knowledge from authoritative sources (arxiv, PubMed, Google Scholar, JSTOR, OpenAlex, Crossref, Semantic Scholar) plus standards bodies (NIST, IETF/RFC, OWASP, ISO, sector regulators). Use when you want an audit that flags algorithms, architectural choices, or business rules violating established norms, standards, or best practices — e.g. 'is our APR calculation correct per lending norms?', 'does our crypto follow NIST?', 'is this consensus approach sound?' — each finding tied to a real, fetched citation. Extracts falsifiable claims across algo/arch/biz layers, routes each to the right source class, verifies against fetched evidence, and adversarially refutes before reporting; emits a severity-graded cited report with UNCONFIRMED for anything ungrounded. Not a linter, SAST, or CVE scanner — it reasons about norms, not syntax. |
| x-spec-version | 1 |
| license | MIT |
| compatibility | Needs an agent harness with subagent fan-out and WebFetch/WebSearch; bundled helpers run via `uv run` (fetch_sources.py) and python3 stdlib (report_lint.py). |
| metadata | {"author":"dhanesh","version":"1.1.0","tags":"audit,research,citations,standards,verification,architecture,business-logic"} |
base-in-reality
A read-only, research-grounded repository audit. It answers one question for each
notable design decision in a repo: does this violate an established norm, standard,
algorithm, or best practice — provably, against a real source?
The defining rule: no fabricated authority. Every finding is tied to a source the
agent actually fetched in-session. Ungrounded claims are reported as UNCONFIRMED, never
as violations.
When to use
Use when you want to sanity-check a codebase, architecture, or business logic against the
state of the art and against domain standards — e.g. "is our APR calculation correct per
lending norms?", "does our crypto follow NIST?", "is this consensus approach sound?",
"does our ML eval avoid known leakage pitfalls?". Works on any repo; adapts to its
domain(s).
Invariants (do not violate)
- Read-only by default. Never edit code. The only write path is
--annotate, which
inserts comment markers only — never logic.
- No fabricated citations. Cite only URLs/DOIs fetched this session. Ungrounded ⇒
UNCONFIRMED. See references/verdict-rubric.md.
- Adversarial gate. No
VIOLATION/DEVIATION is reported without surviving a
refutation pass.
- No silent truncation. If
--max-claims caps extraction, list what was dropped in
the report's Dropped-claims log.
Flags
--annotate — also insert # BASE-IN-REALITY[<sev>]: <one-line> — see <report> markers
at finding locations (the only code-touching mode). Default: off.--layer algo|arch|biz — restrict to one layer. Default: all three.--domain <x> — override auto-detected domain. Default: auto.--since <ref> — audit only the diff vs <ref>. Default: whole repo.--max-claims N — cap claims per run. Default: 40.
Procedure
Run these six stages. Dispatch subagents where noted (fan-out). On Claude Code you may
instead feed assets/workflow.mjs to the Workflow tool as a deterministic accelerator —
it performs stages 2/4/5 with parallel fan-out; the steps below are the portable path.
Locating the source helper (do this first). The bundled fetch_sources.py is referenced
by a path relative to THIS skill's directory, but the verify subagents (stage 4) run from the
, not from here — a path like will not resolve for them.
Before dispatching any subagent, resolve the helper's ABSOLUTE path once and pass it into each
subagent's prompt:
