Tutorial: Capturing Expert Knowledge

In this tutorial you will capture a piece of expert knowledge as an SMEbit, add a testable check that validates it against data, and group it into a BitBundle narrative. This is how institutional knowledge enters the system — attributed, versioned, and verifiable.

Time: 10 minutes Prerequisites: Tutorial: Your First Build completed

1. The scenario

After exploring your findings in Tutorial #1, you notice that CASE_002 is an outpatient case. You talk to a domain expert who tells you:

“Outpatient cases are often unbilled because the billing trigger only fires for inpatient discharges. This is a known system limitation.”

This is expert knowledge. No data model can derive it. But it explains your findings.

2. Write an SMEbit (Level 0 — Observation)

Create afs/smebits/smebit_outpatient_billing_gap.yaml:

smebit_id: smebit_outpatient_billing_gap
version: "1.0.0"

provider:
  name: "Domain Expert"
  role: "Operations Manager"
  date: "2026-03-24"

scope:
  tenant_id: "*"
  source_system: null
  time_range:
    from: null
    until: null

category: system
tags: [billing, outpatient, known-limitation]
status: active

subject:
  en: "Outpatient billing trigger does not fire automatically"
  de: "Ambulante Abrechnungsauslösung erfolgt nicht automatisch"
  fr: "Le déclencheur de facturation ambulatoire ne se déclenche pas automatiquement"

content:
  en: |
    The billing system only triggers automatic invoicing on inpatient
    discharge events. Outpatient cases (day_case, outpatient) must be
    billed manually or through a separate batch process. This explains
    why outpatient cases frequently appear as unbilled in signal findings.
  de: |
    Das Abrechnungssystem löst die automatische Rechnungsstellung nur
    bei stationären Entlassungen aus. Ambulante Fälle müssen manuell
    oder über einen separaten Batch-Prozess abgerechnet werden.
  fr: |
    Le système de facturation ne déclenche la facturation automatique
    que lors des clôtures de dossiers stationnaires. Les cas ambulatoires
    doivent être facturés manuellement ou via un processus batch séparé.

why:
  en: "Legacy system design — the billing interface was built for inpatient workflows only."
  de: "Legacy-Systemdesign — die Abrechnungsschnittstelle wurde nur für stationäre Workflows entwickelt."
  fr: "Conception système héritée — l'interface de facturation a été conçue uniquement pour les flux stationnaires."

anchors:
  - probe_id: probe_unbilled_cases
    hypothesis_id: null
    entity_type: Case

This is a Level 0 SMEbit — an observation. No SQL, no verdict. It lives in the registry and is visible in the Explorer.

3. Build and explore

jinflow make
jinflow explore

Navigate to SMEbits (press S). You’ll see your SMEbit with the provider attribution, category badge, and the full explanation.

4. Add a testable check (Level 1)

Now let’s make this verifiable. Add a check block to the same YAML:

check:
  description:
    en: "Verify that unbilled cases are predominantly outpatient"
    de: "Überprüfen, dass nicht abgerechnete Fälle überwiegend ambulant sind"
    fr: "Vérifier que les cas non facturés sont principalement ambulatoires"
  entity_type: Case
  query: |
    SELECT
      CASE WHEN outpatient_ratio > 0.5 THEN 'confirmed' ELSE 'violated' END AS status,
      outpatient_ratio,
      unbilled_outpatient,
      unbilled_total
    FROM (
      SELECT
        COUNT(*) FILTER (WHERE case_type != 'inpatient') AS unbilled_outpatient,
        COUNT(*) AS unbilled_total,
        ROUND(COUNT(*) FILTER (WHERE case_type != 'inpatient')::DECIMAL / NULLIF(COUNT(*), 0), 2) AS outpatient_ratio
      FROM {{ ref('gold_cases') }} c
      WHERE NOT EXISTS (
        SELECT 1 FROM {{ ref('gold_billing_events') }} b
        WHERE b.case_id = c.case_id
      )
    )
  expect: confirmed

Now the SMEbit is Level 1 — it compiles to a dbt model and produces a verdict: confirmed (yes, unbilled cases are mostly outpatient) or violated (the expert’s claim doesn’t hold).

5. Rebuild and see the verdict

jinflow make
jinflow explore

The SMEbit detail page now shows a verdict badge — confirmed or violated. The expert’s knowledge is now testable on every build, across every tenant.

6. Bundle into a narrative (BitBundle)

Create afs/bitbundles/bb_billing_system_limitations.yaml:

bitbundle_id: bb_billing_system_limitations
version: "1.0.0"

curator:
  name: "Analyst"
  role: "Data Engineering"
  date: "2026-03-24"

scope:
  tenant_id: "*"

title:
  en: "Billing System Limitations"
  de: "Einschränkungen des Abrechnungssystems"
  fr: "Limitations du système de facturation"

narrative:
  en: |
    The organization's billing system has known limitations that explain
    recurring patterns in signal findings. These are not data quality
    issues — they are system behaviors documented by domain experts.
    Understanding them prevents false alarms and guides process
    improvement priorities.
  de: |
    Das Abrechnungssystem der Organisation hat bekannte Einschränkungen,
    die wiederkehrende Muster in den Signal-Befunden erklären.
  fr: |
    Le système de facturation de l'organisation a des limitations connues
    qui expliquent les schémas récurrents dans les résultats des sondes.

smebits:
  - smebit_id: smebit_outpatient_billing_gap
    note:
      en: "The primary limitation — outpatient cases bypass the automatic billing trigger."
      de: "Die Haupteinschränkung — ambulante Fälle umgehen den automatischen Abrechnungsauslöser."
      fr: "La limitation principale — les cas ambulatoires contournent le déclencheur automatique."

status: active
tags: [billing, system-limitations]

7. Build and see the bundle

jinflow make
jinflow explore

Navigate to Use Cases (press U). Your BitBundle appears with the narrative and its member SMEbit linked below.

What you learned

• SMEbits capture atomic expert knowledge — attributed to a named provider, with scope and lifecycle
• Level 0 (observation) is documentation only — no SQL, no verdict
• Level 1 (check) adds a testable assertion that produces confirmed/violated/no_data on every build
• The why field distinguishes data from knowledge — it captures the reason behind the observation
• BitBundles group related SMEbits into a narrative — the “story” layer
• Anchors link SMEbits to signals, theses, and entities for discoverability

Next steps

• Tutorial: Onboarding a New Tenant — receive data, init, build, snapshot (coming soon)
• SMEbit Reference — all SMEbit fields
• BitBundle Reference — all BitBundle fields
• Glossary — every term explained