Documentation How it works
Quality gates
The checks a report must pass, and why a useful-looking report can still be blocked.
On this page
Why a report can be blocked
A fluent report is not necessarily a grounded report. GridPreview combines deterministic checks with independent review so that attractive wording cannot substitute for usable evidence.
All trust gates remain blocking. Configuration can specify thresholds, but cannot turn required provenance or safety checks into advisory warnings. A failed required check prevents a validated result.
The checks
| Gate | What it checks |
|---|---|
| Provenance | Available evidence has an identifiable source and verifiable URL |
| Citation integrity | Referenced evidence exists in the collected evidence set |
| Numeric and safety claims | Required sections, exact structured coverage, reference mappings, units and prohibited binding assertions |
| Citation threshold | Factual claims have valid, available claim-level source references |
| Freshness | Available evidence has a sufficiently recent justified observation or publication date |
| Numeric consistency | Reported quantities match cited source quantities with compatible dimensions |
| Semantic entailment | Independent review covers the expected sentences and supports the factual assertions |
Configured thresholds
The current default configuration uses:
{
"citation": { "minimumScore": 0.90, "severity": "blocking" },
"freshness": { "minimumScore": 0.80, "severity": "blocking" },
"numericConsistency": { "minimumScore": 0.95, "severity": "blocking" }
}
Saved runs use their own configuration snapshot. Passing one metric does not override another failed gate.
For freshness, the allowed age is (1 - minimumScore) × 365 days. A score of 0.80 corresponds to about 73 days. Live observations use observedAt; publication-based records use publishedAt or an established effectiveAt. Retrieval alone never makes an old fact fresh.
Facts versus questions
Pure information requests, fact-free recommendations and disclaimers do not assert external facts that require source entailment. Classification is deliberately conservative; uncertain prose can be independently reviewed rather than exempted by its punctuation.
“Ask an installer to assess the roof” is different from “Ask an installer because the roof supports the panels.” The latter contains a factual premise. Numeric and safety assertions cannot bypass checks simply by appearing in a recommendation.
A narrow source-outage disclosure is checked against saved collection status. “BAG was unavailable” does not use an unavailable BAG record as proof of a building characteristic. More specific timeout claims require a matching saved collection warning.
Exact references and units
Review slots preserve the writer’s authoritative references. The system does not fix a missing source by attaching all section citations to a claim. Missing, duplicate and unrelated reviews are explicit failures.
Numeric consistency uses exact claim-level references. Power, energy and annual energy are separate dimensions; a source value in kWh cannot support a claim in kW merely because the number matches.
Interpret failure details
Semantic failures identify the sentence, section, reviewer judgment, score, reason and additional code-level rejection conditions. A reviewer may say “supported” while code still rejects a missing or unavailable reference.
The correct response is to improve evidence, correct the sentence or disclose a limitation. Do not lower a threshold, drop citations or skip checks just to obtain a pass. A blocked report is useful diagnostic output, not a successful assessment.