Tutoriel : Du Finding au Verdict

Dans ce tutoriel, vous allez prendre un Signal Finding, écrire une Thesis pour tester si le pattern est réel, et écrire un Verdict pour expliquer pourquoi cela se produit. C’est le workflow analytique principal — le chemin de « quelque chose semble anormal » à « voici pourquoi et que faire ».

Durée : 20 minutes Prérequis : Tutoriel : Votre premier build terminé (vous avez un tenant fonctionnel avec probe_unbilled_cases)

1. Où nous en étions

Après le Tutoriel #1, vous avez :

• Un tenant avec des données de cas et de facturation
• Un Signal (probe_unbilled_cases) qui trouve les cas sans événements de facturation
• Des findings pour CASE_002 et CASE_004

Maintenant la question est : est-ce un problème systémique, ou juste du bruit ?

2. Écrire une Thesis

Une Thesis (anciennement appelée hypothesis) est une question métier testable. Créez 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."

Points clés :

• evidence référence votre Signal existant avec le rôle primary (poids 3)
• verdict.thresholds fixe la barre : score >= 0.6 = confirmed, >= 0.3 = plausible
• interpretation fournit un texte lisible pour les 4 résultats possibles
• Tout le texte est trilingue (en/de/fr)

3. Construire et vérifier le statut de la Thesis

jinflow make

Ouvrez l’Explorer :

jinflow explore

Naviguez vers Theses (touche H). Vous devriez voir thesis_billing_gap avec un statut. Avec 2 cas sur 5 non facturés (40%) et un Signal primary avec des findings, le score de preuve devrait pousser cela vers confirmed ou plausible selon le nombre et le score des findings.

Cliquez la carte Thesis pour voir la page de détail : le texte d’interprétation, la chaîne de preuves reliant à probe_unbilled_cases et les findings du Signal.

4. Écrire un Verdict

Maintenant expliquez pourquoi cela se produit. Créez 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."

Points clés :

• thesis_id lie à la Thesis que nous venons d’écrire
• conditions définit quand ce Verdict se déclenche (au moins 2 cas non facturés)
• confidence.base est 0.7, boosté à 0.9 si plus de 3 findings
• explanation dit pourquoi (process failure : déclencheur de facturation manquant)
• recommendation dit que faire (automatiser la vérification)

5. Construire et voir le tableau complet

jinflow make
jinflow explore

Naviguez vers Theses → cliquez thesis_billing_gap. Sous l’interprétation, vous devriez maintenant voir la section Verdict avec :

• Badge de cause racine : process_failure
• Barre de confiance
• Texte d’explication
• Texte de recommandation

6. La pyramide analytique en action

Vous venez de construire une chaîne analytique complète :

C’est la méthode jinflow : détecter → évaluer → expliquer → recommander. Chaque couche est du YAML, compilé en SQL, déterministe et reproductible.

Ce que vous avez appris

• Une Thesis (anciennement hypothesis) agrège les preuves des Signals et produit un statut (confirmed/plausible/not_observed/insufficient)
• Un Verdict (anciennement diagnosis) explique pourquoi une Thesis confirmée est vraie, avec cause racine et recommandation
• La chaîne de preuves est visible dans l’Explorer : Finding → Thesis → Verdict
• Tout le texte est trilingue — chaque interprétation, explication et recommandation a en/de/fr

Prochaines étapes

• Tutoriel : Capturer les connaissances expertes — écrire des SMEbits et BitBundles
• Référence Thesis — tous les champs Thesis
• Référence Verdict — tous les champs Verdict
• Glossaire — chaque terme expliqué