Skip to Content
PlatformExplanationAbout evidence and assertions

About evidence and assertions

Evidence is the first product and the one the others depend on. A question frames what the program wants to know; sources are where the answers might be; findings are statements drawn from sources; hypotheses are proposals supported or contradicted by findings; gaps are what the sources do not cover. Every statement declares an assertion kind and an origin.

The problem

The brief requires that each proposed conclusion link back to its supporting evidence and clearly distinguish observed results from interpretations, assumptions and suggestions produced by agents. The brand voice guide says the same in fewer words: distinguish observed results from interpretations, assumptions, hypotheses and proposed actions, and never style an agent’s interpretation as a verified scientific finding.

How it works

  • A finding carries question_id, source_ids[], statement, assertion_kind, origin and a confidence_note. A hypothesis carries supporting_finding_ids[] and contradicting_finding_ids[] so the case for and against is explicit.
  • assertion_kind is one of observation, interpretation, assumption, suggestion; origin is human or agent. The chip prints both; agent-origin records show “Agent-generated, for review”.
  • Sources arrive by hand (Add source) or through a connection sync, and are linked to a question, finding or hypothesis with POST .../sources/{source_id}/links.
  • The three evidence agent runs (evidence_compare, evidence_gaps, evidence_hypotheses) read a question’s findings and sources and write new findings, gaps or hypotheses with origin = agent. They never edit an accepted record.
  • A hypothesis is decided by a person with evidence.hypotheses.approve (accepted or rejected, with a rationale); a gap is addressed or dismissed with evidence.gaps.manage.

Why this design

  • Four kinds and not a confidence number: a number cannot say whether a statement was observed or inferred; the kind can, and a confidence note still fits beside it.
  • Origin on the record and not on the run only: readers meet the finding in a list, not the run; the chip has to be on the record.
  • Sources as first-class records: a citation string alone cannot be synced, linked to several findings or archived; a source can.
  • Gaps as records: what the sources do not cover is itself a finding about the evidence, and an agent can propose it for a person to address or dismiss.

Consequences and limits

  • A finding without a source is legitimate only as an assumption or a suggestion (ADR 0004); the API stores the list, the discipline is the author’s.
  • The success tone is reserved for statuses such as accepted and answered; an observation is not “true”, it is traceable.
  • Seeded records carry illustrative = true and the “Illustrative” label, so a screenshot of the evidence screens never looks like real program data.
About programsAbout agent actions and records