Enforce Epistemic Quality in Documents

Clarity Gate is a pre-ingestion verification system that checks whether a document properly marks its claims as validated fact versus hypothesis, projection, or assumption - the question it asks is "if another LLM reads this document, will it mistake assumptions for facts?" It runs nine verification points across three groups: epistemic checks (hypothesis-vs-fact labeling, uncertainty-marker enforcement on forward-looking statements, assumption visibility, and flagging authoritative-looking unvalidated data like unsourced percentage tables), data-quality checks (internal numeric consistency, implicit causation, future state described as present), and verification routing (temporal coherence of dates and versions, and flagging externally verifiable claims like pricing or statistics for follow-up). Passing documents are emitted as Clarity-Gated Documents (CGD), a .cgd.md format with required YAML frontmatter fields (clarity-gate-version, clarity-status, hitl-status, hitl-pending-count, points-passed, document-sha256), an <!-- CLARITY_GATE_END --> end marker, and - when any claim needs human confirmation - a ## HITL Verification Record section. Two bundled Python scripts, claim_id.py and document_hash.py, compute deterministic hash-based claim IDs and a canonicalized SHA-256 document hash per the format spec.

python scripts/claim_id.py "Base price is $99/mo" "api-pricing/1"
# Output: claim-75fb137a

Use it before ingesting documents into RAG systems, before sharing documents with other AI systems, after writing specs or methodology docs, when a document contains projections or hypotheses, before publishing unvalidated claims, or when handing documentation off between LLM sessions. Critically, Clarity Gate verifies form, not truth - it checks whether claims are properly marked as uncertain, not whether they are actually true, so a model could hallucinate a fact and then "pass" the gate by tagging it with a source marker; the skill explicitly requires mandatory Human-In-The-Loop (HITL) verification before any document is declared PASS. It also does not classify document types, restructure documents, add references, or evaluate writing quality.

Input is a Markdown document with claims to review; output is a Clarity Gate report listing issues by severity (Critical, Warning, Temporal, Externally Verifiable Claims) plus a two-round confirmation flow - Round A for quick confirmation of claims derived from a witnessed source, Round B for claims genuinely requiring human verification, each recorded in a ## HITL Verification Record table. A validated document carries rag-ingestable: true, computed by the validator and never set manually, and it is only true when status is CLEAR | REVIEWED with no open exclusion blocks - documents containing an unresolved <!-- CG-EXCLUSION --> block are rejected wholesale, not partially ingested. Source of Truth (SOT) files are validated as CGDs carrying a tier: block and a ## Verified Claims table with required columns (Claim, Value, Source, Verified) in a fixed order.

Ships as a standalone skill with no external API dependency beyond its own bundled claim_id.py/document_hash.py scripts; it implements the Clarity Gate Format Specification v2.1 and is designed to sit ahead of any RAG ingestion pipeline. Related projects from the same author include Source of Truth Creator, for authoring epistemically calibrated docs from scratch, and Stream Coding, a documentation-first methodology.

Teams and individual authors preparing documentation, specs, or reports for ingestion into RAG knowledge bases or hand-off between LLM sessions, who need a structured way to catch confident-sounding hallucination risks before they enter a knowledge base - with the caveat that a human must still confirm the flagged claims.