Grounding

Overview

Grounding is what makes a Reason8 reaction yours and not a generic LLM guess. A grounded panel reacts through personas built from your real user evidence — reviews, tickets, verbatims, telemetry, founder briefs — rather than from a blank-slate audience description. An ungrounded panel runs purely from the audience text you pass.

reason8_ask exposes an explicit grounding axis (auto | ungrounded | grounded): auto uses a grounded set when one matches your audience, and runs ungrounded when none does. The reason8_research_* track has no grounding parameter — it grounds automatically when the run's target_audience matches a seeded set, and otherwise runs ungrounded.

The provenance ladder

Not all evidence is equal. Reason8 ranks every piece of evidence on a provenance ladder, strongest to weakest:

observed_telemetry > real_verbatim > real_artifact > client_belief > agent_inference

Real signal overrides stated belief. When observed behavior contradicts what someone said they would do, the observed signal wins.

Confidence is rules-derived from this ladder — it is never agent-self-rated. A persona does not get to declare itself confident; its confidence follows from the strength and corroboration of the evidence underneath it. Contradictions in the evidence are kept as first-class signal, not averaged away.

Persona status

Each grounded persona carries an honest status:

• supported — backed by enough real evidence to stand on.
• speculative — grounded but thin; treat its read with caution.
• insufficient_evidence — not enough real signal to support a persona here.

When the evidence is sparse, Reason8 returns fewer personas and honest gaps — it never fills empty slots with invented people to hit a target count. A thin grounded read is flagged as speculative (and surfaces on a reaction as verified.is_speculative: true) rather than dressed up as solid. The synthesis.gaps field names what the evidence did not cover.

How an agent seeds evidence

To ground a set, an agent feeds Reason8 your real user evidence through the onboarding / grounding interview path. That path normalizes each source onto the provenance ladder and builds a persona set you can then target by audience.

Seeding entry point. The grounding interview is the contract entry point for seeding (internally the reason8_seed_persona flow). It is delivered via the portal onboarding path and is not yet exposed as a standalone MCP tool with a public schema — so don't call it directly from an agent today. Seed through the onboarding / grounding interview path instead.

Seed once; later reason8_ask calls whose audience matches that set run grounded automatically (the default grounding: "auto"), and reason8_research_* runs ground automatically when their target_audience matches. The synthesis.grounding_used field tells you which set a reaction matched, and synthesis.evidence_version tells you which evidence snapshot it used.

Document goal: ground the personas in your real users so the reactions reflect your audience, with the firewall keeping thin reads honest.