Instrument Author Cheat Sheet

Tip

Print this page (Cmd+P) for a desk reference.

Instrument Locations

Type	Directory	Filename pattern	ID rule
Probe	probes/	probe_*.yaml	probe_id = filename
Assessment	probes/	assessment_*.yaml	probe_id = filename
Hypothesis	hypotheses/	hyp_*.yaml	hypothesis_id = filename
Diagnosis	diagnoses/	diag_*.yaml	diagnosis_id = filename
SMEbit	smebits/	smebit_*.yaml	smebit_id = filename
BitBundle	bitbundles/	bb_*.yaml	bitbundle_id = filename
Report	reports/	report_*.yaml	report_id = filename

Probe Types

Type	What it checks
balance	Two aggregates match (e.g., usage vs billing)
mandatory_item	Entity has required items
distribution_outlier	Z-score anomalies
duplicate	Duplicate records by field combo
ratio	Numerator/denominator within tolerance
trend	Worsening metrics over time
temporal_sequence	Events in expected order
silver_audit	Silver-layer data quality
entity_filter	Entities matching conditions
enrichment	Dimension + fact derived metrics
reconciliation	Dual fact-table comparison
hand_written	Custom SQL (bypass DSL)
assessment	Aggregate findings from other probes

Severity Rules

Standard probes:

severity_rules:
  - above: 10.0          # if value > 10 → high
    level: high
  - above: 2.0           # if value > 2 → medium
    level: medium
  - default: low          # everything else

Assessments (compound):

severity_rules:
  - conditions:
      - field: finding_count
        above: 50
      - field: total_risk
        above: 10000
    level: high
  - field: finding_count
    above: 10
    level: medium
  - default: low

Evidence Roles (Hypotheses)

Role	Weight	Impact
primary	3	Must have findings for “confirmed”
supporting	2	Strengthens the case
context	1	Background, not decisive
counter	varies	Reduces score if findings exist

Must have at least one primary entry.

Verdict Thresholds (Hypotheses)

verdict:
  thresholds:
    confirmed: 0.65       # score >= 0.65 → confirmed
    plausible: 0.35       # score >= 0.35 → plausible
                          # score < 0.35  → not_observed

Rule: 0 <= plausible < confirmed <= 1

Root Cause Categories (Diagnoses)

Category	What it means
process_failure	Broken business process
system_failure	IT system malfunction
data_quality	Stale or inconsistent data
behavioral	Human workarounds
structural	Organizational misalignment
external	Supplier, regulatory

Confidence (Diagnoses)

confidence:
  base: 0.6              # starting confidence
  boost_if:
    - probe_id: probe_x
      field: finding_count
      above: 50
      boost: 0.2          # max 0.3 per boost

SMEbit Levels

Level	Has check block?	Produces verdict?
0 (Observation)	No	Registry only
1 (Check)	Yes	confirmed / violated / no_data

SMEbit Categories

data_quality mapping business_rule process system seasonal historical structural

Report Section Types

Type	Needs	Shows
kpi_grid	items	Key metric boxes
callout	items	Highlighted callout
severity_bar	query	Severity distribution
table	query	Data table
text	content	Static text
footer	text	Footer text
chart_bar	query	Bar chart
chart_trend	query	Time-series chart

Query Template Helpers

{{ gold('entity_name') }}        -- resolves to {{ ref('gold_entity') }}
{{ silver('entity_name') }}      -- resolves to {{ ref('silver_entity') }}
{{ ref('model_name') }}          -- dbt reference
{{ var("tenant_id") }}           -- current tenant

Contracts

Contract	Used by	Reference
gold.v1	Probes	Gold entity fields
silver.v1	Silver audit probes	Silver entity fields
findings.v1	Assessments	Finding output fields
diagnosis.v1	(output)	Diagnosis verdict fields
smebit.v1	(output)	SMEbit registry + verdict
bitbundle.v1	(output)	BitBundle registry
report.v1	(output)	Report registry + data

Workflow

1. Write YAML in afs/
2. jinflow make           ← validates, compiles, builds
3. jinflow explore        ← see results
4. Iterate

All validators and compilers run automatically as part of make. No manual compiler invocation needed.

Tri-lingual Fields

All user-facing text must have en, de, fr:

title:
  en: "English title"
  de: "Deutscher Titel"
  fr: "Titre français"

Applies to: statement, interpretation, explanation, recommendation, subject, content, why, narrative, title, description, display_name.