How a finding earns the right to exist

A finding is evidence, not an opinion.

Every finding row carries the telemetry window it was drawn from, the specific tools the agent ran, the confidence the agent reached, and the dollar amount it sized. A claim that does not pass those four gates does not become a finding. The platform refuses to write a row that cannot defend itself in audit.

Every claim is hypothesis, not problem.

Findings are labelled H1, H2, H3 (hypotheses ranked by confidence), not P1, P2 (problems asserted as facts). The distinction matters because the agent is not present at the customer's site and cannot know with certainty that a compressor is degraded or a setpoint is wrong. The label commits to evidence-based reasoning and refuses to assert what was not stated by the operator or proven by the data.

Anchored to a specific evidence window.

Every finding names the time range its evidence was drawn from, the entities (assets, spaces, processes) it applied to, the meters or sensors that produced the data, and the baseline it compared against. A finding that cannot point at a window did not earn the right to exist.

Dollar amount or no row.

Findings without a defensible dollar figure are not filed. The agent's session may record an observation as 'seen but not sized,' and the next session at the next cadence may pick up the thread. The findings ledger is reserved for actionable conclusions, which means quantified conclusions.

Supersession, never mutation.

When a later finding addresses the same root cause as an earlier one with new evidence, the new finding supersedes the old via supersedes_id. Both rows remain on disk. The customer reads the latest; the audit reads the chain. Editing a prior finding's text or amount is structurally impossible.

The customer reads in business language, never internal vocabulary.

Internal framings (the Five Areas, the agent code keys, the strategy types, the playbook names) do not appear in customer-facing reports. The customer reads what is happening, what it costs, and what the recommended next step is. The vocabulary that the platform uses internally is for engineering, not for the operator.

H1

Highest confidence. Direct evidence visible in telemetry, corroborated across at least two independent signals, with no plausible alternative explanation surviving the agent's hypothesis space. Suitable for direct work-order dispatch by the Engineer, direct tariff-switch recommendation by the Broker, direct opportunity sizing by the Consultant.

H2

Medium confidence. Strong telemetry signal with a plausible alternative explanation the agent could not rule out. The finding is filed but accompanied by the alternative and the diagnostic step the operator can run to disambiguate. Common for early-stage equipment-degradation diagnoses where signature evidence is suggestive but baseline residual is the only confirmer.

H3

Lower confidence. Pattern visible in the data but the agent has not crossed the area's threshold for autonomous action. The row carries a note explaining what additional evidence would lift it to H2. Operators read H3 findings as prompts rather than recommendations.

Tariff-window weighted

Used for waste findings on metered loads. Per-tick energy delta multiplied by the tariff rate at that tick, summed over the evidence window, projected forward at the prior week's load shape.

Peak-shaving

Used for penalty findings on demand charges. Demand window kW reduction multiplied by the demand charge per kW, projected over the billing period.

Marginal tariff

Used for opportunity findings on tariff switches. Modelled tariff applied to the prior twelve months of load, compared against current tariff applied to the same load, net of switching cost.

Capex ROI

Used for opportunity findings that require investment (solar, battery, retrofit). Net present value over the asset's expected life, sensitivity-banded for tariff and discount-rate assumptions.

Continuation cost

Used for silence findings on equipment degradation. Cost of doing nothing, sized as the gap between current consumption and the rebuilt-equipment baseline, integrated over the time before secondary failure becomes likely.

The report

The long-form customer artefact. Three-to-six page PDF or web view that walks the customer through the period: what was found, what was sized, what was done, what is recommended. Findings appear grouped by area with the customer-facing title and the dollar amount; the underlying evidence is linked but not in-line.

The brief

The short-form customer artefact. One-page summary for periods where nothing material happened or for new customers before the first month of evidence has accumulated. Findings appear as a list with title and amount only.

The dashboard

The live surface. Findings show up in the active queue grouped by state (Recommended → In Progress → Monitored → Resolved). Operators triage from this surface; the dashboard is where state transitions happen.

The session detail

The deep-link surface. From any finding, the operator can open the session that produced it and read the full reasoning trace: which tools the agent called, what evidence it gathered, what hypotheses it considered and rejected. Used for dispute resolution and for training new operators.

The scoping conversation

When an operator chooses to act on a finding, the Diagnostic agent and the operator scope an Intervention in conversation: target entities, expected savings, IPMVP option. The finding becomes the origin row on the Intervention; the Intervention carries the scope; the strategy or the retrofit delivers the work.

What the work costs

If the Intervention needs equipment, the Consultant's finding (or the Engineer's, for retrofits) carries the capex band and the sensitivity analysis, so the customer sees the range before committing. Wattif charges for the work and passes equipment through at cost; it does not fund the deployment or take a percentage of what the deployment saves.

The finding stays linked

On Intervention creation, the finding's intervention_id column is populated. The finding remains in its original state (Recommended → In Progress) until the Intervention itself reaches Verified, at which point the finding moves to Resolved with a backreference to the verifications row.

Findings that do not become Interventions

Most findings are addressed without an Intervention at all: a tariff switch the customer makes directly, a setpoint change the operator applies, a contractor visit on a service contract that pre-exists. The finding closes through the normal state machine without ever touching the Intervention model.

confidence_below_threshold

The agent's session reached a hypothesis but could not cross the area's minimum confidence. The session records the hypothesis as 'observed but not actionable'; no finding is filed. The next session at the next cadence may pick up the thread with additional evidence.

amount_undefendable

The agent has a hypothesis with sufficient confidence but cannot construct a defensible dollar figure (tariff data missing, evidence window too short for projection, sizing method not applicable to the load class). The session records the gap; no finding is filed until sizing becomes possible.

evidence_window_too_short

An agent attempting to file a finding from a window shorter than the area's minimum (forty-eight hours for waste, fourteen days for silence, twenty-eight days for opportunity sizing) is refused at write time. The platform requires enough evidence to be statistically meaningful per the area's standard.

supersession_required_no_prior

An agent attempting to file a finding that overlaps an existing un-superseded finding on the same root cause is required to either supersede or merge. Two parallel findings on the same issue with conflicting amounts is a refused state; one must defer to the other.

customer_vocabulary_violation

Internal vocabulary (Five Areas labels, agent code keys, playbook names) in a finding's title or summary is rejected at write time. The platform pattern-matches against the internal vocabulary list and refuses to file. This is a build-time check, not a runtime one; the surface that produces customer-facing copy strips internal vocabulary before submission.