Verdict YAML Reference

Field-level specification for verdict YAML definitions.

Overview

Property	Value
File location	diagnoses/diag_*.yaml
ID rule	diagnosis_id must match filename (without .yaml)
Validator	python3 scripts/diagnosischeck.py
Compiler	python3 scripts/diagnosiscompile.py
Compiler dry-run	python3 scripts/diagnosiscompile.py --check

Fields

Field	Type	Required	Valid values
diagnosis_id	string	yes	Must match filename
version	string	yes	Semantic version (e.g. "1.0")
hypothesis_id	string	yes	Must reference an existing hypotheses/*.yaml
root_cause_category	string	yes	See Root Cause Categories
root_cause_id	string	yes	Freeform identifier for the specific root cause
conditions	list	yes	Min 1 entry; see Conditions Block
confidence	dict	yes	See Confidence Block
explanation	dict	yes	{en, de, fr} tri-lingual text
recommendation	dict	yes	{en, de, fr} tri-lingual text
created_at	string	no	ISO date
modified_at	string	no	ISO date

Root Cause Categories

Category	Description
process_failure	Broken or incomplete business process
system_failure	IT system malfunction or integration gap
data_quality	Stale, missing, or inconsistent master data
behavioral	Human behavior patterns (workarounds, skipped steps)
structural	Organizational or contractual misalignment
external	External factors (supplier, regulatory)

Conditions Block

Each entry in the conditions list:

Field	Type	Required	Description
probe_id	string	yes	Must reference an existing probes/*.yaml
field	string	yes	Aggregate field from signal findings (e.g. finding_count, money_at_risk)
above	number	yes	Numeric threshold

Rules:

• All conditions must be met (AND logic) for the verdict to fire.
• All referenced probe_id values must have a corresponding YAML file in probes/.
• The verdict only evaluates when its parent thesis has status confirmed.

Confidence Block

Field	Type	Required	Valid values
base	float	yes	0.0-1.0
boost_if	list	no	See below

Each boost_if entry:

Field	Type	Required	Valid values
probe_id	string	yes	Must reference an existing probes/*.yaml
field	string	yes	Aggregate field from signal findings
above	number	yes	Numeric threshold
boost	float	yes	0.0-0.3

Rules:

• base + sum(all boosts) should not exceed 1.0.
• Each individual boost must be between 0.0 and 0.3.

Verdict Output

Each verdict produces one row per tenant in diagnosis_verdicts (only for confirmed theses where all conditions are met):

Column	Type	Description
diagnosis_id	string	Verdict identifier
tenant_id	string	Tenant identifier
hypothesis_id	string	Parent thesis identifier
root_cause_category	string	Category from the YAML
root_cause_id	string	Specific root cause identifier
confidence	float	base + applicable boosts
finding_count	integer	Total findings across condition signals
money_at_risk	numeric	Sum of money_at_risk from condition signals
hypothesis_evidence_score	float	Evidence score from the parent thesis

Minimal Example

diagnosis_id: diag_billing_workflow_gap
version: "1.0"
hypothesis_id: hyp_unbilled_services

root_cause_category: process_failure
root_cause_id: billing_step_skipped

conditions:
  - probe_id: probe_revenue_leakage
    field: finding_count
    above: 10
  - probe_id: probe_billing_completeness
    field: money_at_risk
    above: 5000

confidence:
  base: 0.6
  boost_if:
    - probe_id: probe_revenue_leakage
      field: money_at_risk
      above: 50000
      boost: 0.2

explanation:
  en: "A gap in the billing workflow causes services to be delivered without triggering an invoice."
  de: "Eine Luecke im Verrechnungsprozess fuehrt dazu, dass Leistungen ohne Rechnungsstellung erbracht werden."
  fr: "Une lacune dans le processus de facturation fait que des prestations sont fournies sans declenchement de facture."

recommendation:
  en: "Implement a mandatory billing check before case closure in the ERP system."
  de: "Einen obligatorischen Verrechnungscheck vor Fallabschluss im ERP-System einrichten."
  fr: "Mettre en place un controle de facturation obligatoire avant la cloture du cas dans le systeme ERP."