Verdict YAML Reference

Field-level specification for verdict YAML definitions.

Overview

Property	Value
File location	verdicts/verdict_*.yaml
ID rule	verdict_id must match filename (without .yaml)
Validator	python3 scripts/verdictcheck.py
Compiler	python3 scripts/verdictcompile.py
Compiler dry-run	python3 scripts/verdictcompile.py --check

Fields

Field	Type	Required	Valid values
verdict_id	string	yes	Must match filename
version	string	yes	Semantic version (e.g. "1.0")
thesis_id	string	yes	Must reference an existing theses/*.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
signal_id	string	yes	Must reference an existing signals/*.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 signal_id values must have a corresponding YAML file in signals/.
• 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
signal_id	string	yes	Must reference an existing signals/*.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 verdict_findings (only for confirmed theses where all conditions are met):

Column	Type	Description
verdict_id	string	Verdict identifier
tenant_id	string	Tenant identifier
thesis_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
thesis_evidence_score	float	Evidence score from the parent thesis

Minimal Example

verdict_id: verdict_billing_workflow_gap
version: "1.0"
thesis_id: thesis_unbilled_services

root_cause_category: process_failure
root_cause_id: billing_step_skipped

conditions:
  - signal_id: signal_revenue_leakage
    field: finding_count
    above: 10
  - signal_id: signal_billing_completeness
    field: money_at_risk
    above: 5000

confidence:
  base: 0.6
  boost_if:
    - signal_id: signal_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."