Tutorial: From Finding to Verdict

In this tutorial you will take a signal finding, write a thesis to test whether the pattern is real, and write a verdict to explain why it happens. This is the core analytical workflow — the path from “something looks wrong” to “here’s why and what to do.”

Time: 20 minutes Prerequisites: Tutorial: Your First Build completed (you have a working tenant with probe_unbilled_cases)

1. Where we left off

After Tutorial #1, you have:

• A tenant with cases and billing data
• A signal (probe_unbilled_cases) that finds cases without billing events
• Findings for CASE_002 and CASE_004

Now the question is: is this a systemic problem, or just noise?

2. Write a thesis

A thesis (formerly called a hypothesis) is a testable business question. Create afs/theses/thesis_billing_gap.yaml:

thesis_id: thesis_billing_gap
version: "1.0.0"
short_code: BGAP

statement:
  en: "Are cases systematically left unbilled, indicating a broken billing workflow?"
  de: "Werden Fälle systematisch nicht abgerechnet, was auf einen fehlerhaften Abrechnungsprozess hindeutet?"
  fr: "Les cas sont-ils systématiquement non facturés, indiquant un processus de facturation défaillant?"

category: financial_anomaly

evidence:
  - probe_id: probe_unbilled_cases
    role: primary
    weight: 3

verdict:
  thresholds:
    confirmed: 0.6
    plausible: 0.3

interpretation:
  confirmed:
    en: "Multiple cases have no billing events. This indicates a systematic gap in the billing workflow — cases are being closed without triggering the billing process."
    de: "Mehrere Fälle haben keine Abrechnungsereignisse. Dies deutet auf eine systematische Lücke im Abrechnungsprozess hin."
    fr: "Plusieurs cas n'ont pas d'événements de facturation. Cela indique une lacune systématique dans le processus de facturation."
  plausible:
    en: "Some unbilled cases exist but the pattern is not conclusive. Could be delayed billing or manual exceptions."
    de: "Einige nicht abgerechnete Fälle existieren, aber das Muster ist nicht schlüssig."
    fr: "Certains cas non facturés existent mais le schéma n'est pas concluant."
  not_observed:
    en: "All cases have corresponding billing events. No billing gap detected."
    de: "Alle Fälle haben entsprechende Abrechnungsereignisse. Keine Abrechnungslücke erkannt."
    fr: "Tous les cas ont des événements de facturation correspondants. Aucune lacune détectée."
  insufficient:
    en: "Not enough case and billing data to evaluate the billing gap thesis."
    de: "Nicht genügend Fall- und Abrechnungsdaten, um die These zu bewerten."
    fr: "Pas assez de données pour évaluer la thèse de lacune de facturation."

Key points:

• evidence references your existing signal with role primary (weight 3)
• verdict.thresholds set the bar: score >= 0.6 = confirmed, >= 0.3 = plausible
• interpretation provides human-readable text for all 4 possible outcomes
• All text is tri-lingual (en/de/fr)

3. Build and check the thesis status

jinflow make

Open the Explorer:

jinflow explore

Navigate to Theses (press H). You should see thesis_billing_gap with a status. With 2 out of 5 cases unbilled (40%), and a primary signal with findings, the evidence score should push this to confirmed or plausible depending on the finding count and score.

Click the thesis card to see the detail page: the interpretation text, the evidence chain linking to probe_unbilled_cases, and the signal’s findings.

4. Write a verdict

Now explain why this is happening. Create afs/verdicts/verdict_billing_process_gap.yaml:

verdict_id: verdict_billing_process_gap
version: "1.0.0"

thesis_id: thesis_billing_gap

root_cause_category: process_failure
root_cause_id: missing_billing_trigger

conditions:
  - probe_id: probe_unbilled_cases
    field: finding_count
    above: 1

confidence:
  base: 0.7
  boost_if:
    - probe_id: probe_unbilled_cases
      field: finding_count
      above: 3
      boost: 0.2

explanation:
  en: "The billing system does not automatically trigger invoicing when a case is closed. Cases closed outside of normal hours or via the fast-track discharge path bypass the billing trigger entirely."
  de: "Das Abrechnungssystem löst bei Fallabschluss nicht automatisch eine Rechnungsstellung aus. Fälle, die ausserhalb der normalen Geschäftszeiten oder über den Schnellentlassungspfad abgeschlossen werden, umgehen den Abrechnungsauslöser vollständig."
  fr: "Le système de facturation ne déclenche pas automatiquement la facturation lors de la clôture d'un cas. Les cas clôturés en dehors des heures normales ou via le parcours de sortie rapide contournent entièrement le déclencheur de facturation."

recommendation:
  en: "Implement an automated billing check that runs on case closure. Flag any case closed without a corresponding billing event within 24 hours. Audit the fast-track discharge pathway for billing integration."
  de: "Implementieren Sie eine automatische Abrechnungsprüfung bei Fallabschluss. Markieren Sie jeden Fall, der ohne entsprechendes Abrechnungsereignis innerhalb von 24 Stunden abgeschlossen wird."
  fr: "Mettre en place une vérification automatique de facturation à la clôture du cas. Signaler tout cas clôturé sans événement de facturation correspondant dans les 24 heures."

Key points:

• thesis_id links to the thesis we just wrote
• conditions define when this verdict triggers (at least 2 unbilled cases)
• confidence.base is 0.7, boosted to 0.9 if more than 3 findings
• explanation says why (process failure: missing billing trigger)
• recommendation says what to do (automate the check)

5. Build and see the full picture

jinflow make
jinflow explore

Navigate to Theses → click thesis_billing_gap. Below the interpretation, you should now see the Verdict section with:

• Root cause badge: process_failure
• Confidence bar
• Explanation text
• Recommendation text

6. The analytical pyramid in action

You’ve just built a complete analytical chain:

This is the jinflow method: detect → evaluate → explain → recommend. Each layer is YAML, compiled to SQL, deterministic, and reproducible.

What you learned

• A thesis (formerly thesis) aggregates evidence from signals and produces a status (confirmed/plausible/not_observed/insufficient)
• A verdict (formerly verdict) explains why a confirmed thesis is true, with root cause and recommendation
• The evidence chain is visible in the Explorer: finding → thesis → verdict
• All text is tri-lingual — every interpretation, explanation, and recommendation has en/de/fr

Next steps

• Tutorial: Capturing Expert Knowledge — write SMEbits and BitBundles (coming soon)
• Thesis Reference — all thesis fields
• Verdict Reference — all verdict fields
• Glossary — every term explained