Skip to content

Sense 22: The Legend — labels that explain themselves

Sense 22 · Steady · Under question · Last touched 2026-08-20

  • last_verified: 2026-07-27

Synced from docs/design/sense_22_the_legend.md in the engine repo — that’s the source; this page is a build-time mirror.

Every classified value carries the rule that produced it, the threshold that set the rule, what it means, and what to do about it. The label and its legend travel together.

Today our enum columns are signs. The Legend says: every sign must carry its story.

Status: proposed Author: the owner + Claude (conversation, 2026-04-27 — surfaced while designing the spread_signature classifier for the pricing model)


A label is data; an explanation is somewhere else.

When gold_article_price_spread flags material 620260 with spread_signature = 'mis_channeled', the user sees the string. To understand what it means, they have to:

  1. Open the dbt model SQL.
  2. Find the CASE WHEN that produced the value.
  3. Read the surrounding comments — if any.
  4. Hunt for the threshold (< 1.00 CHF? where did that come from?).
  5. Guess what action the label implies.

The same pattern repeats everywhere we classify:

  • Signal severity is 'low' | 'medium' | 'high' — but where is the rule that decides? In the signal compiler? In the YAML? In the signal author’s head?
  • Action status is 'proposed' | 'in_progress' | 'completed' | 'rejected' — what’s the difference between rejected and not-yet- proposed? What action does each invite?
  • Subject Matter category is 'data_quality' | 'process' | 'system' | ... — how should one decide which to use when authoring? (Field stays on the smebit_* slug; only the display label changed.)
  • Verdict confidence is a number, but the buckets that turn numbers into labels live in code.
  • Material class is 'CONSUMABLE' | 'MEDICATION' | ... — derived how, from what columns?

Each is a small piece of meaning that the engine produces and the human must reverse-engineer.

The user can ask “what does this label mean?” and the system has no way to answer except by handing back source code.


A Legend is a label that travels with its meaning. When a classified value appears anywhere — a table cell, a chart axis, a signal finding, a status badge — the system knows:

  • The rule that produced it (how it was assigned)
  • The threshold that set the rule (the parameter)
  • The description (what it means in plain language)
  • The action (what to do when you see it)
  • The icon/color (how it should render)

These five components together are a Legend entry. A column whose values come from a known set has a Legend. The system reads the Legend the same way it reads the data.

The principle: classifications must be self-describing artifacts, not invisible code.

When a CFO hovers on a severity = 'high' badge, they see “≥3 findings of money_at_risk above 50,000 CHF — escalate to operations review.” They don’t need to read SQL. The label brought its meaning along.


A meaningful amount of the foundation is in place.

  • Entity YAML already supports display_name (multilingual), column_formats, column_tooltips, column_links — the precedent for column-level metadata is established.
  • Glossary (packs/numetrix/glossary/registry_glossary.yaml) already carries multilingual descriptions for signals.
  • Tooltips are already wired through to the dimension page — we use them in gold_article_price_spread for price_spread_pct, distinct_prices, etc.
  • Entity registry is the compile artifact that surfaces YAML metadata to JinDesk at runtime.
  • Signal YAML already carries severity (a string label) and a brief interpretation template — but nothing that tells the user how a severity gets assigned.
  • Action cells in notebook YAML have status (an enum) but no rules-of-progression document.

What’s missing is the discipline that connects them. The Legend is that discipline.


Every classified value (an enum) is described by a Legend, a declarative block that lives in YAML alongside the artifact that owns the column.

spread_signature:
description:
en: "Why this material's catalogue prices disagree, and what to do about it."
de: "Warum die Katalogpreise dieses Materials uneinig sind, und was zu tun ist."
fr: "Pourquoi les prix catalogue de ce matériau divergent, et l'action à prendre."
thresholds:
stub_price_chf: 1.00
substantial_movements: 10
values:
catalogue_ghost:
icon: "👻"
color: "#9ca3af"
rule: "0 movements in any channel"
description:
en: "Material exists in the catalogue but never transacts."
action:
en: "Filter out of analyses that imply usage."
mis_channeled:
icon: "↔"
color: "#dc2626"
rule: "Movements in only one channel; the other channel has a price below stub_price_chf"
description:
en: "The material lives in one channel; the other has a stub price for catalogue completeness."
action:
en: "Gap 3 fix: supply_org_matched filters out the stub side."
cross_channel:
icon: "⇄"
color: "#f59e0b"
rule: "Substantial movements (≥substantial_movements) in both channels"
description:
en: "Both channels actually transact. Investigate UoM and pricing differences."
action:
en: "Gap 2/3 territory — may need UoM Subject Matter curation."
catalogue_incorrect:
icon: "⚠"
color: "#ea580c"
rule: "Real movements (including RECEIVE events) but a catalogue price is below stub_price_chf"
description:
en: "The material moves through procurement but a catalogue price is implausible."
action:
en: "Curate via a Subject Matter entry; the price is wrong, not the channel."
single_channel:
icon: "→"
color: "#10b981"
rule: "Movements in only one channel; the other doesn't carry the material at all"
description:
en: "Single-channel material — expected pattern."
action:
en: "No action — expected for single-org materials."
sentinel_tail:
icon: "🪦"
color: "#6b7280"
rule: "All catalogue prices below stub_price_chf"
description:
en: "All known prices are sentinel-class. No real activity to value."
action:
en: "Should be filtered at silver. Investigate if any rows reach this state."
  • rule — a single sentence describing the test that fires the label. References thresholds by name.
  • thresholds — named numeric (or string) parameters of the rules. Declared once at the Legend level, used by all rules.
  • description — multilingual prose explaining what the label means in human terms.
  • action — multilingual recommended response. “What does the reader do when they see this?”
  • icon + color — how the badge should render. Optional but encouraged.
  • It is not the SQL that materialises the column. The SQL reads the thresholds via dbt vars (var('stub_price_chf', 1.00)); the rule logic still lives in SQL. The Legend is the declarative documentation, not the implementation.
  • It is not the data itself. A Legend describes the shape of values; the values appear in rows.
  • It is not static. A pack maintainer can edit thresholds and recompile; the Legend updates everywhere it surfaces.

The same protocol covers many kinds of classification across the system. Six families:

The motivating case. spread_signature, material_class, channel, catalogue_type, signature columns on any analytical gold table.

Today every signal carries severity and category. Both are strings without explicit Legends.

signal_id: signal_revenue_leakage
severity: medium
category: financial_anomaly

Sense 22 says: define what medium means for THIS signal — at what threshold, with what action. A signal can declare its own Legend overriding the pack default:

classifications:
severity:
thresholds:
high_money_at_risk_chf: 100000
medium_money_at_risk_chf: 10000
rules:
high: "money_at_risk >= high_money_at_risk_chf"
medium: "money_at_risk >= medium_money_at_risk_chf"
low: "below medium_money_at_risk_chf"
action:
high: "Escalate immediately; CFO review within 24h"
medium: "Review at next operations meeting"
low: "Track in dashboard; no action required"

Today: proposed | in_progress | completed | rejected. Nowhere is the rule of progression documented. Sense 22:

classifications:
status:
values:
proposed: { rule: "Initial state at cell creation", action: "Triage at standup" }
in_progress: { rule: "Owner accepted and started work", action: "Daily check-in expected" }
completed: { rule: "Work delivered AND result documented", action: "Read-only; archive after 90d" }
rejected: { rule: "Decision not to do; result documents why", action: "Read-only; reference if revisited" }

Verdicts carry a confidence (0.0–1.0). Today the bucketing (“high/medium/low confidence”) lives in display code. Sense 22 makes the bucket boundaries part of the verdict YAML.

data_quality | mapping | business_rule | process | system | seasonal | historical | structural — each category should declare what kind of knowledge belongs here and what reader should consult it.

6. Material classes / channels / supply_orgs

Section titled “6. Material classes / channels / supply_orgs”

Tenant-defined enums. Today 'CONSUMABLE', 'MEDICATION', 'PHA', 'LOG' are strings with implicit semantics. Each could carry its own Legend.


Legends live next to the artifact whose column they describe:

ArtifactWhere the Legend lives
Dimension column (e.g. spread_signature)Entity YAML in afs/entities/
Signal severity / categorySignal YAML in afs/signals/
Action statusNotebook YAML or a tenant-level action_legend.yaml
Verdict confidenceVerdict YAML in afs/verdicts/
Subject Matter categoryPack-level legend file in afs/contracts/
Material classTenant-level lookup file

Pack-level defaults vs tenant-level overrides follow the same config-cascade pattern as the rest of jinflow (engine → pack → tenant).


The Legend appears wherever its labels appear:

The cheap-now first surface. Hovering on the spread_signature column header shows the full Legend table. This is what we ship today.

Hovering on a specific cell value (e.g. mis_channeled) shows just that one entry’s rule + description + action. The colour and icon render in-cell.

”(?) About these classifications” panel

Section titled “”(?) About these classifications” panel”

A small expandable panel below the table on the dimension page. Shows the full Legend with thresholds, rules, descriptions, actions — a one-stop reference for the column.

Clicking a Legend entry in the panel filters the table to that class. “Show me only catalogue_incorrect materials.” The chip displays the icon + colour from the Legend.

Typing !spread_signature:mis_channeled in the search bar uses the declared values as a discoverable autocomplete source.

Signal findings already render severity badges; with Sense 22 the badge knows its colour, icon, and tooltip text from the Legend, not from hardcoded UI logic.


  • Sense 13 (The Canvas) — Form follows Data. The Legend tells the panel what colour, icon, and grouping to use. Today panels hardcode their own palette; with Sense 22 they ask the data.
  • Sense 14 (The Signal) — Signals already classify (severity, category, polarity). Sense 22 formalises what those classifications mean.
  • Sense 21 (The Heartbeat) — Beat 5 (notify) needs interpretable labels. “Severity went from low to high” is meaningful only if both labels carry their meaning. Sense 22 is the substrate Sense 21’s awareness rides on.
  • Identity & Passes — capabilities have types (ui_visibility, action, api_gate, dynamic_filter). Each is a classification whose meaning belongs in a Legend.

A growing log of incidents that share the same root cause: a label without a legend.

Symptom A — spread_signature design (2026-04-27)

Section titled “Symptom A — spread_signature design (2026-04-27)”

While building the spread classifier, we needed to document the rule “stub price < 1.00 CHF, substantial movements ≥ 10.” No existing mechanism carried this. We considered (a) hard-coding into SQL with a comment, (b) putting it in column tooltips, (c) extending the YAML schema. The decision to ship (b) today and pursue (c) as Sense 22 crystallised the pattern.

Symptom B — signal_price_spread_inconsistency is mislabelled (2026-04-27)

Section titled “Symptom B — signal_price_spread_inconsistency is mislabelled (2026-04-27)”

The signal flags every price_spread_pct > 20% finding as category = 'data_quality'. After today’s investigation we know that at RMC, the findings are mostly structural (mis-channeling, catalogue ghosts), not DQ. The category is wrong, but there’s no formal mechanism to correct it without re-authoring the signal YAML — and once corrected, future readers won’t know why.

A Legend on signal.category with rule and last_validated could flag mis-applied categories for review. The category gains provenance; the analyst can ask “is this still the right label?”

Future incidents will land here.


Establish the principle and the protocol.

What we ship 2026-04-27, alongside the spread_signature classifier:

  • Use existing column_tooltips mechanism for spread_signature in article_price_spread.yaml.
  • Tooltip text contains the full Legend table inline.
  • Thresholds documented in the SQL header comment AND the tooltip.
  • A small markdown-style description on the column-header hover.

This gets ~80% of the user value with no schema change.

Formal schema for classifications block on entity YAML:

classifications:
<column_name>:
description: { en: ..., de: ..., fr: ... }
thresholds: { ... }
values:
<enum_value>:
rule: ...
description: { ... }
action: { ... }
icon: ...
color: ...

Compiler (entitycompile.py) bakes this into entity_registry. JinDesk reads it via the existing registry-loading pathway.

Phase 3 — JinDesk “About these classes” panel

Section titled “Phase 3 — JinDesk “About these classes” panel”

A new component under each dimension table that renders the Legend as a structured panel: rules table, threshold list, action column. Locale-aware. Filter chips that respect the Legend’s colour.

Phase 4 — Hover-on-value tooltips and badges

Section titled “Phase 4 — Hover-on-value tooltips and badges”

Per-cell hover shows the matching Legend entry. Status/severity badges everywhere in JinDesk pull their colour and icon from Legends rather than hardcoded UI dictionaries.

Phase 5 — Adopt for Signals, Verdicts, Actions, Subject Matter

Section titled “Phase 5 — Adopt for Signals, Verdicts, Actions, Subject Matter”

Migrate existing severity, category, status, confidence fields to use the Legend pattern. Each artifact YAML gains its own classifications block; pack-level defaults supply the common shapes.

Search grammar (per lib/utils/search.ts) auto-completes from declared Legend values. Filters in the dimension page render with Legend colours/icons.


Currently implementing. Status: implementing. The in-flight work is described in the roadmap / phases above; the canonical map of running surfaces (URLs, CLI verbs, source pointers) will land here once the first phase ships.


  1. Pack-default vs tenant-override resolution. When a pack declares a Legend for severity and a tenant overrides one threshold, do we merge or replace? Lean: per-key merge with tenant-side winning (consistent with config.yml cascade).

  2. Colour/icon authority. Should colours come from a small curated palette (consistency across JinDesk) or be free- form per Legend (flexibility but visual chaos)? Lean: a curated palette declared at engine level; Legends pick from it by name.

  3. Internationalisation of rules. The rule text is currently English-only in the proposed schema. Should it be multilingual? Lean: yes. Same en/de/fr structure as description and action.

  4. Legend versioning. When a threshold changes, do we record the prior values? KLS snapshots already capture the AFS state, so versioning is implicit via git. But for “this finding was tagged high under threshold X; the threshold has since changed to Y”, we may want an explicit last_changed_at field per threshold. Open.

  5. Dynamic Legends. Some classifications depend on tenant data (e.g. severity thresholds derived from a percentile of the tenant’s data). Can a Legend be parameterised by a SQL query, or only by static thresholds? Lean: static for v1; dynamic via computed thresholds in v2.

  6. Computed Legend values. Today’s spread_signature is a classification. But Legends could also describe computed summaries like “this row is in the top 5% by money_at_risk.” Should that live in the Legend (as a description of the column’s meaning) or stay as ad-hoc tooltips? Open.

  7. Discoverability. When a new pack maintainer wants to know “what enums does this entity use?”, today they read the YAML. With Legends, the entity registry has a structured answer. Do we surface a /<tenant>/legends index page that lists every Legend in the tenant? Lean: yes, eventually.


jinflow classifies. It produces labels: severities, statuses, categories, signatures. Today those labels are signs — strings with implicit meaning the user has to decode by reading source.

The Legend says: every label travels with its rule, threshold, description, action, and icon. When someone sees mis_channeled in a cell, they hover and the system tells them what it means and what to do — in their language, with provenance.

Six families of classification (column enums, signal severities, action statuses, verdict confidences, Subject Matter categories, material classes) all become structured. The label and its legend travel together.

The owner will never have to grep the SQL to remember what proposed meant.


Numerical neighbors: ← Sense 22 — The Legend: Implementation · Sense 23: The Engine’s Seam — Where the Engine and the Tenant Disagree →

jazzisnow jinflow is a jazzisnow product
v0.65.0 · built 2026-11-13 10:20 UTC