Sense 22: The Legend — labels that explain themselves
Ce contenu n’est pas encore disponible dans votre langue.
Sense 22 · Steady · Under question · Last touched 2026-08-20
- last_verified: 2026-07-27
Synced from
docs/design/sense_22_the_legend.mdin 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)
What pulled us in
Section titled “What pulled us in”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:
- Open the dbt model SQL.
- Find the CASE WHEN that produced the value.
- Read the surrounding comments — if any.
- Hunt for the threshold (
< 1.00 CHF? where did that come from?). - 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 thesmebit_*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.
The Vision
Section titled “The Vision”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.
What Already Exists
Section titled “What Already Exists”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_spreadforprice_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 briefinterpretationtemplate — 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.
The Legend Protocol
Section titled “The Legend Protocol”Every classified value (an enum) is described by a Legend, a declarative block that lives in YAML alongside the artifact that owns the column.
A Legend entry — five components
Section titled “A Legend entry — five components”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."The five components
Section titled “The five components”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.
What a Legend is NOT
Section titled “What a Legend is NOT”- 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.
Where It Applies
Section titled “Where It Applies”The same protocol covers many kinds of classification across the system. Six families:
1. Dimension column enums
Section titled “1. Dimension column enums”The motivating case. spread_signature, material_class,
channel, catalogue_type, signature columns on any analytical
gold table.
2. Signal classifications
Section titled “2. Signal classifications”Today every signal carries severity and category. Both are
strings without explicit Legends.
signal_id: signal_revenue_leakageseverity: mediumcategory: financial_anomalySense 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"3. Action statuses (notebook actions)
Section titled “3. Action statuses (notebook actions)”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" }4. Verdict confidence buckets
Section titled “4. Verdict confidence buckets”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.
5. Subject Matter categories
Section titled “5. Subject Matter categories”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.
Where It Lives
Section titled “Where It Lives”Legends live next to the artifact whose column they describe:
| Artifact | Where the Legend lives |
|---|---|
Dimension column (e.g. spread_signature) | Entity YAML in afs/entities/ |
| Signal severity / category | Signal YAML in afs/signals/ |
| Action status | Notebook YAML or a tenant-level action_legend.yaml |
| Verdict confidence | Verdict YAML in afs/verdicts/ |
| Subject Matter category | Pack-level legend file in afs/contracts/ |
| Material class | Tenant-level lookup file |
Pack-level defaults vs tenant-level overrides follow the same config-cascade pattern as the rest of jinflow (engine → pack → tenant).
How It Surfaces
Section titled “How It Surfaces”The Legend appears wherever its labels appear:
Column-header tooltip
Section titled “Column-header tooltip”The cheap-now first surface. Hovering on the spread_signature
column header shows the full Legend table. This is what we ship
today.
Hover-on-value
Section titled “Hover-on-value”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.
Filter chips
Section titled “Filter chips”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.
Search grammar
Section titled “Search grammar”Typing !spread_signature:mis_channeled in the search bar uses the
declared values as a discoverable autocomplete source.
Severity rendering
Section titled “Severity rendering”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.
Connection to Other Senses
Section titled “Connection to Other Senses”- 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.
Symptoms in the wild
Section titled “Symptoms in the wild”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?”
Symptom C — placeholder
Section titled “Symptom C — placeholder”Future incidents will land here.
Implementation Roadmap
Section titled “Implementation Roadmap”Phase 0 — This paper
Section titled “Phase 0 — This paper”Establish the principle and the protocol.
Phase 1 — Cheap-now tooltip pattern
Section titled “Phase 1 — Cheap-now tooltip pattern”What we ship 2026-04-27, alongside the spread_signature classifier:
- Use existing
column_tooltipsmechanism forspread_signatureinarticle_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.
Phase 2 — Entity YAML schema extension
Section titled “Phase 2 — Entity YAML schema extension”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.
Phase 6 — Search and filter integration
Section titled “Phase 6 — Search and filter integration”Search grammar (per lib/utils/search.ts) auto-completes from
declared Legend values. Filters in the dimension page render with
Legend colours/icons.
How this manifests in jinflow
Section titled “How this manifests in jinflow”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.
Open Questions
Section titled “Open Questions”-
Pack-default vs tenant-override resolution. When a pack declares a Legend for
severityand a tenant overrides one threshold, do we merge or replace? Lean: per-key merge with tenant-side winning (consistent withconfig.ymlcascade). -
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.
-
Internationalisation of rules. The
ruletext is currently English-only in the proposed schema. Should it be multilingual? Lean: yes. Same en/de/fr structure asdescriptionandaction. -
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
highunder threshold X; the threshold has since changed to Y”, we may want an explicitlast_changed_atfield per threshold. Open. -
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.
-
Computed Legend values. Today’s
spread_signatureis 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. -
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>/legendsindex page that lists every Legend in the tenant? Lean: yes, eventually.
The Elevator Pitch
Section titled “The Elevator Pitch”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_channeledin 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
proposedmeant.
Numerical neighbors: ← Sense 22 — The Legend: Implementation · Sense 23: The Engine’s Seam — Where the Engine and the Tenant Disagree →