Instrument Author Cheat Sheet

Tip

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

The Seven Instrument Types

jinflow currently ships seven authorable instrument types, arranged in the analytical diamond:

#	Instrument	What it does	Compiles to
1	Signal	Detect a pattern in Gold data (or Silver for audits) — the leaf-level instrument	signal_findings__<id>.sql
2	Perspective	Aggregate findings from multiple Signals into an entity-level lens	signal_findings__<id>.sql (signal with type: perspective)
3	Thesis	Evaluate a business question against Signal evidence — produces a Verdict status	thesis_verdicts__<id>.sql
4	Verdict	Explain the root cause of a confirmed Thesis with actionable recommendation	verdict_findings__<id>.sql
5	Subject Matter	Atomic, attributed expert knowledge — the Wisdom layer	smebit_registry.sql (+ verdict SQL for Level 1)
6	Dossier	Curated narrative grouping of Subject Matter entries	bitbundle_registry.sql + bitbundle_memberships.sql
7	Report	Audience-targeted structured summary — executive, operational, data-quality	report_registry.sql (+ per-section models)

Everything is YAML-defined. All seven types get validated by a <type>check.py script and compiled by a <type>compile.py script — both run automatically inside jinflow make.

Instrument Locations

Type	Directory	Filename pattern	ID rule
Signal	signals/	signal_*.yaml	signal_id = filename
Perspective	perspectives/	perspective_*.yaml	signal_id = filename (type: perspective)
Thesis	theses/	thesis_*.yaml	thesis_id = filename
Verdict	verdicts/	verdict_*.yaml	verdict_id = filename
Subject Matter	smebits/	smebit_*.yaml	smebit_id = filename (slug preserved)
Dossier	bitbundles/	bb_*.yaml	bitbundle_id = filename (slug preserved)
Report	reports/	report_*.yaml	report_id = filename

Filename slugs smebit_* and bb_* (and the directories smebits/ and bitbundles/) are preserved for git-history compatibility — the vocabulary rename to Subject Matter / Dossier is display-facing only.

Signal Types

Thirteen types, each with its own DSL block in the YAML:

Type	What it checks
balance	Two aggregates match (e.g. usage vs billing)
mandatory_item	Qualifying entities have required items
distribution_outlier	Z-score anomalies against reference
duplicate	Duplicate records by field combination
ratio	Numerator / denominator within tolerance
trend	Worsening metric over time
temporal_sequence	Events in expected order
silver_audit	Silver-layer data quality (validity or activity variant)
perspective	Aggregate findings across multiple Signals
entity_filter	Entities matching a set of conditions
reconciliation	Dual fact-table comparison
enrichment	Dimension + fact derived metric
hand_written	Custom SQL (bypass the DSL, keep the contract)

Severity Rules

Standard Signals:

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

Perspectives (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 (Theses)

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 (Theses)

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

Thesis Categories (fixed enum)

Value	Meaning
compliance	Regulatory / policy exposure
data_quality	Data integrity concern
financial_anomaly	Direct revenue / cost impact
operational	Everything else operational

No custom categories — validator enforces the enum.

Thesis Short Codes

Four-letter codes for URL slugs and inter-thesis references. Validator requires a vowel (a, e, i, o, u) at position 2 or 3 so the code can be spoken aloud.

• ✗ FRR — three consonants
• ✓ RELI — E at position 2
• ✓ FIRM — I at position 2

Root Cause Categories (Verdicts)

Category	What it means
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 behaviour patterns (workarounds, skipped steps)
structural	Organizational or contractual misalignment
external	External factors (supplier, regulatory)

Confidence (Verdicts)

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

Subject Matter Kinds

Kind	Scope	Portable?
wisdom	Cross-tenant / pack-level knowledge	Yes — travels with the pack
fiftycents	Tenant-specific, contextual knowledge	No — anchored to one tenant

For wisdom: scope.tenant_id: "*" or absent. For fiftycents: scope.tenant_id must name a real tenant.

Subject Matter Levels

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

Subject Matter Categories

data_quality · mapping · business_rule · process · system · seasonal · historical · structural

Always fill the why: field. The validator warns (not errors) if absent — but the nudge ensures the question is asked. The difference between data and knowledge is the why.

Report Section Types

Type	Needs	Shows
kpi_grid	items	Key metric boxes
callout	items	Highlighted callout
severity_bar	query	Severity distribution bar
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	Signals	Gold entity fields
silver.v1	silver_audit Signals	Silver entity fields
findings.v1	Perspectives (input)	Signal-findings output shape
verdict.v1	Verdicts (output)	Verdict findings output shape
smebit.v1	Subject Matter (output)	Registry + Level-1 verdict shape
bitbundle.v1	Dossiers (output)	Registry + memberships shape
report.v1	Reports (output)	Registry + section shape

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.

Workflow

1. Write YAML under the tenant AFS
2. jinflow make <pack>.<tenant>    ← validates, compiles, builds
3. jinflow explore <pack>.<tenant> ← see results
4. Iterate

All <type>check.py validators and <type>compile.py compilers run automatically inside jinflow make. You can invoke them standalone with --check (dry-run) and --afs <path> while authoring for immediate feedback.