Skip to content

Claims: Small, Sourced, Verifiable

Claims break wiki pages down into individual statements with subject, predicate, object, confidence, status and a verbatim quote as evidence. This makes agreement and disagreement precise.

≈ 10 min readSoftwareAIMethodology

“Our publishing is secure, fast and reliable.” The sentence sounds good and is hardly usable as a claim. It contains three judgments, none of them has a criterion, and a source could at most support parts of it. A reviewer would have to accept or reject the whole sentence, even though they might only be able to confirm a documented rollback mechanism as part of reliability.

A knowledge base should therefore store small statements as subject / predicate / object. The page text stays readable for people. Beneath it, claims form the units that can be cited, checked, disputed and retired one by one. Confidence and status answer different questions.

A claim says exactly one thing#

The subject names the thing, the predicate the relationship or property, and the object the concrete value. A good claim can be understood without the rest of the paragraph on the page.

{
  "subject": "content-release",
  "predicate": "rollback_mechanism",
  "object": "switch the active pointer to an immutable revision"
}

The form resembles a simple RDF triple, but it doesn’t force you to model the entire domain as a universal graph. Within a space, a controlled vocabulary emerges that fits its questions. rollback_mechanism can make sense where releases are compared; in an HR space it would be meaningless.

Claims that are too large combine several verifiable statements. Claims that are too small lose their meaning. content-release / uses / pointer would be atomic, but it doesn’t explain what the pointer is used for. The wording should be narrow enough for a contradiction and complete enough for a reader.

flowchart TD
    A["Statement from source"] --> Q{"one domain<br/>assertion?"}
    Q -->|several| S["split into several claims"]
    Q -->|one| C{"understandable<br/>without the paragraph?"}
    C -->|no| E["make the object more precise"]
    C -->|yes| V["add quote and status"]

The quote carries the statement#

Every claim points to one or more sources via citations. A citation contains a verbatim excerpt and, optionally, a locator. A quote check can make sure the quote appears verbatim in the archived source text. A claim whose evidence is only paraphrased or made up should be discarded before it reaches review.

{
  "subject": "content-release",
  "predicate": "rollback_mechanism",
  "object": "switch the active pointer to an immutable revision",
  "confidence": 0.94,
  "citations": [
    {
      "source_id": "source_release_docs",
      "quote": "Rollback changes the active release pointer to a previous immutable revision.",
      "locator": "Rollback"
    }
  ]
}

A quote has to support the statement within its scope. If the source only talks about a preview environment, the claim must not turn that into a general production rule. This check can’t be done with string matching alone. The reviewer reads the context.

Several citations are useful when a statement is supported jointly by a contract and observed behavior. The API documentation can describe the intended mechanism, a production report can document its actual use. Many weak sources, however, don’t automatically make a claim stronger.

Confidence is not a truth scale#

confidence describes how sure the generating synthesis was about its mapping. It can help the reviewer look at uncertain proposals first. It is not a substitute for status and not a probability that a statement is true in the world.

type ClaimStatus = "proposed" | "verified" | "disputed" | "deprecated";

type Claim = {
  subject: string;
  predicate: string;
  object: string;
  confidence: number;
  status: ClaimStatus;
};

A claim with confidence: 0.99 stays proposed until approval. An approved claim with confidence: 0.78 can be verified because a person checked the source and the wording. Later, new evidence can make it disputed without reinterpreting the old confidence value.

This separation prevents a convenient shortcut. A threshold like “approve automatically from 0.9” would confuse model self-confidence with domain authority. It makes more sense to turn every knowledge change into a change proposal, regardless of the value in confidence. It is only adopted after human approval.

Status models the lifecycle#

proposed is staging and invisible to normal readers. verified marks an approved statement. disputed makes a traceable conflict visible. deprecated keeps an outdated statement in the history without treating it as the current state.

The lifecycle allows more precise answers than deletion. If a service used a static retry value up to version 2 and shares a budget since version 3, both statements are historically relevant. The old one isn’t removed from all revisions. It gets a status and stays connected to its source.

stateDiagram-v2
    [*] --> proposed
    proposed --> verified: human approval
    proposed --> [*]: rejection
    verified --> disputed: conflicting evidence
    disputed --> verified: conflict resolved
    verified --> deprecated: superseded
    disputed --> deprecated: superseded

The transition from proposed to verified doesn’t happen automatically but only after a human decision. The visible page text can then explain the current state fluently. The claims beneath it preserve which individual statements carry that explanation and which conflicts are still open.

Functional predicates make conflicts exact#

Some relationships may have several objects at the same time. A system can support several export formats. supports_format=markdown doesn’t contradict supports_format=okf. Other relationships should have only one current value per subject, such as primary_database.

A space can declare such functional predicates. If two different objects for the same subject and predicate meet there, the knowledge base can mark both claims as disputed and connect them via contradicts.

{
  "settings": {
    "functional_predicates": [
      "primary_database",
      "current_owner",
      "default_retention_days"
    ]
  }
}

This rule stays deterministic. A model doesn’t have to decide whether two freely worded paragraphs collide semantically. The controlled predicate states in advance exactly where a single current value is expected.

Too many functional predicates would be harmful. Marking supports_format as functional would wrongly put complementary facts in conflict. The vocabulary is therefore a domain decision of the space and belongs in review.

Breaking a paragraph into claims#

A practical example shows the sizing decision. Suppose a source says: “The service runs as a single binary, migrates PostgreSQL on startup, and exposes health and readiness endpoints.” This should not turn into one claim with the object single binary with migrations and probes. Three properties change independently of each other.

[
  {
    "subject": "service-runtime",
    "predicate": "distribution",
    "object": "single self-contained binary"
  },
  {
    "subject": "service-runtime",
    "predicate": "database_migration",
    "object": "runs automatically on startup"
  },
  {
    "subject": "service-runtime",
    "predicate": "exposes_probe",
    "object": "/health and /ready"
  }
]

If a sidecar is added later, it affects the distribution claim. The migration and the probes can stay unchanged. A reviewer sees exactly the small diff. An agent can keep using the two confirmed statements while the first one is being checked.

The cross-check helps: would a change to the object automatically change the other parts of the statement? If not, several claims are appropriate. If a claim would be misleading without its neighboring sentence, it needs a more precise subject or object.

Time and scope belong in the wording too. uses PostgreSQL fits a current architecture if the source describes the whole service. If it only refers to the production deployment, the subject should be service-production-deployment. Precision often comes more easily from a narrower subject than from a long object text.

A claim is not a complete sentence for blog prose. It may stay machine-readable and terse. The concept page then explains how the three properties work together.

A concept is more than its claims#

Claims alone don’t make a readable explanation. A concept still has a title, a summary, Markdown and relationships to other concepts. The page can explain an example, limitations and the historical context.

The claims serve a different purpose. They let you:

  • trace a single statement back to the original quote;
  • mark a contradiction without rejecting the whole page;
  • check only the statements that actually changed in a new revision;
  • limit search hits and agent answers to visible, approved units.

Page text and the structured layer should be revisioned together. A proposal must not already show new text while its claims are invisible or incomplete for readers. Atomic approval makes the new revision current as a unit.

Relations connect, claims provide evidence#

Besides claims, a knowledge base can know directed relationships between concepts: related, part_of, depends_on, contradicts and supersedes. A relation answers how two pages are connected. It doesn’t replace a claim or a citation.

{
  "from_slug": "content-release",
  "kind": "depends_on",
  "to_slug": "immutable-revision"
}

The relation enables navigation and context. The documented fact stays as a claim on one of the pages. Otherwise a mere link would carry a domain statement without naming its wording or its source.

contradicts can arise as a consequence of the functional predicate logic. supersedes fits a traceable replacement where the new term or the new rule replaces the old state. Relations themselves are reviewed and published with the concept revision.

Revisions answer the question of time#

A current claim alone doesn’t explain when it was introduced. A concept history should keep approved, rejected and proposed revisions together with their provenance: which model and which prompt version generated the proposal, which sources were used and which person approved it.

This information doesn’t make a model the author in a legal or domain sense. It documents which technical synthesis path generated the proposal. Reviewer, note and timestamp explain the human decision. Approval, status and revision together make visible how a statement entered the valid body of knowledge – and how it can leave it again.

The history allows a time-related question: which statement was visible in March, before the retention rule was changed? A knowledge service that always returns only the current paragraph can’t answer it reliably. Revisions preserve the state at the time without presenting old claims as valid today.

For teams, this trail becomes especially useful after model or prompt changes. If a new synthesis version proposes noticeably different claims, the affected revisions can be identified and checked specifically. That way, besides the source, you can also trace which model and which prompt version generated the proposal.

A step beyond “Clean Grounding II”#

Clean Grounding II sorted grounding into conventions, documents and API descriptions. The central question was which material belongs in the scarce context for a specific task and how expensive it would be to retrieve it again. That was a working model for individual sessions.

What’s added is a smaller, durable unit between document and context: the claim. An agent doesn’t have to treat a whole page as uniformly binding every time. It can read the current concept revision, check visible claims including their status and open their citations when needed. “Matching document into the context” becomes “matching, approved statement with a way back to the source.”

The older article Fuzzy Matching with Explicit Limits separated a claim with confidence from a fact. The same caution applies here. Confidence helps sort a proposal. Only evidence, review and status determine how the statement appears in the knowledge base.

Checking claims in review#

For a new proposal, four questions are enough. Does the claim assert exactly one thing? Is it understandable without the surrounding paragraph? Does the quote cover exactly this scope? Would a different new value be recognizable as a clear contradiction?

If an answer is no, the claim gets split, worded more narrowly or rejected. This is not a formal word exercise. Small claims reduce the effort later. A changed retention rule then doesn’t require a complete rewrite of the page about storage. Only the affected statement and its explanation get adjusted.

Only statements that matter for search, review, conflicts or provenance get structured. The point is not to map every sentence as a universal ontology. Everything else stays prose; no claim is created for it.

Further reading#

Revised and translated from German with the help of AI.