Sense 14: The Signal

Sense 14 · Steady · Last touched 2026-08-20

• last_verified: 2026-06-05

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

Vocabulary note. This document uses earlier terminology (SMEbit → now Subject Matter, BitBundle / Use Case → now Dossier, Observation at Level 0 → now Statement). Internal identifiers (filenames, dbt tables, contracts) kept their legacy slugs; only the display names changed. The concept is unchanged. See terminology.yaml for canonical definitions.

Not every finding is a problem. Not every problem is financial. A signal is an observation. Its meaning depends on context.

Status: implementing Author: nuMetrix Team

---

What pulled us in

The current probe framework has a fundamental bias: it only sees problems.

• Every probe detects an “anomaly” (negative)
• Every severity says “how bad” (never “how good”)
• Every hypothesis asks “is this bad thing happening?”
• money_at_risk assumes the impact is financial and negative
• 3-level severity (high/medium/low) loses signal when aggregated
• No concept of opportunity, improvement, or health

This shapes what the user sees, thinks, and does. A dashboard of red flags creates anxiety, not insight. The user cannot answer: “What is going well?” “Where are the opportunities?” “Is this getting better or worse?”

The Vision

From anomaly detection to signal detection.

A signal is a typed, directional, multi-dimensional observation. Its meaning depends on the question being asked.

The New Vocabulary

The rename is total — no legacy names survive in code, AFS, or UI.

Layer	Old	New	What it does
Observation	Probe / Finding	Signal	A single typed observation (polarity, score, impact)
Lens	Assessment	Perspective	A named aggregation of signals into an entity-level view
Question	Hypothesis	Thesis	A business question answered by signals and perspectives
Judgment	Diagnosis	Verdict	A root cause explanation with confidence and recommendation
Knowledge	SMEbit	Subject Matter	Display-only rename 2026-04-13; internal slug smebit_* preserved
Narrative	BitBundle	Dossier	Display-only rename 2026-04-13; internal slug bb_* / bitbundle_* preserved

The Diamond

         Verdict
        (why + what to do)
            ↑
          Thesis
        (is this true?)
         ↑      ↑
  Perspective   Signal
    (lens)    (observation)

Clean, directional, polarity-neutral. Every layer can be positive or negative. No medical, laboratory, or academic metaphors.

File System Rename

Old path	New path
probes/	signals/
probes/probe_*.yaml	signals/signal_*.yaml
probes/assessment_*.yaml	perspectives/perspective_*.yaml
hypotheses/hyp_*.yaml	theses/thesis_*.yaml
diagnoses/diag_*.yaml	verdicts/verdict_*.yaml
contracts/findings_contract.v1.json	contracts/signal_contract.v1.json

Script Rename

Old	New
probecheck.py	signalcheck.py
probecompile.py	signalcompile.py
proberegistry.py	signalregistry.py
hypothesischeck.py	thesischeck.py
hypothesiscompile.py	thesiscompile.py
diagnosischeck.py	verdictcheck.py
diagnosiscompile.py	verdictcompile.py

dbt Model Rename

Old	New
probe_findings__signal_*	signal_findings__signal_*
probe_findings__assessment_*	perspective_findings__perspective_*
probe_registry	signal_registry
hypothesis_verdicts	thesis_verdicts
hypothesis_registry	thesis_registry
diagnosis_verdicts	verdict_findings
diagnosis_registry	verdict_registry
platform_probe_findings	(retired — the platform layer was removed 2026-05-29 with the single-tenant KLS direction)

YAML Field Rename

Old field	New field
probe_id	signal_id
probe_version	signal_version
probe_category	signal_category
hypothesis_id	thesis_id
diagnosis_id	verdict_id
source_probes	source_signals
severity	severity (kept as display label, derived from score)
money_at_risk	money_at_risk (kept for backward compat, derived from impact_value)

JinDesk Route Rename

Old route	New route
/{tenant}/probes	/{tenant}/signals
/{tenant}/findings	/{tenant}/findings (unchanged — still the findings list)
/{tenant}/findings/{probe_id}	/{tenant}/findings/{signal_id}
/{tenant}/hypotheses	/{tenant}/theses
/{tenant}/hypotheses/{id}	/{tenant}/theses/{id}

Signal Model

Core properties

signal:
  polarity: positive | negative | neutral
  score: 0-100                    # continuous intensity
  direction: improving | stable | worsening | null
  impact:
    value: -12000                 # signed number
    unit: CHF                     # or: count, percent, days, custom
    dimension: financial          # financial | operational | quality | cultural | strategic

Polarity

Polarity	Meaning	Example
negative	Risk, problem, anomaly	Revenue leakage, expired catalog
positive	Strength, opportunity, health	Price stability, complete traceability
neutral	Observation, no judgment	Material count, classification label

Score (0-100)

Replaces the 3-level severity as the source of truth for signal strength.

Score	Display	Meaning (negative)	Meaning (positive)
0-20	low	Negligible risk	Marginal strength
20-50	medium	Moderate risk	Notable strength
50-80	high	Significant risk	Strong signal
80-100	critical	Urgent action needed	Exceptional

Thresholds are configurable per tenant via the config engine:

display:
  signal:
    thresholds: [20, 50, 80]
    labels:
      negative: [negligible, moderate, significant, critical]
      positive: [marginal, notable, strong, exceptional]

Severity labels are a display concern, not a data concern.

Direction

Direction	Meaning
improving	Score decreasing (negative) or increasing (positive) over time
stable	Score within ±5% over 3+ periods
worsening	Score increasing (negative) or decreasing (positive) over time
null	No temporal data or first observation

Impact

Impact is not money. It is a typed value with a dimension:

Dimension	Unit examples	What it measures
financial	CHF, EUR, USD	Revenue, cost, savings
operational	count, hours, days	Process disruptions, delays
quality	percent, score	Error rates, completeness
cultural	count, score	Workarounds, compliance fatigue
strategic	count, score	Supplier dependency, market exposure

The value is signed: negative = cost/risk, positive = opportunity/savings.

Perspectives (reformed Assessments)

A Perspective is a named lens — not a rigid bundle.

Key properties

• Selects signals (does not own them)
• Produces a continuous score per entity (0-100)
• Reports polarity balance (positive vs negative signal count)
• The same signal can appear in multiple perspectives with different weights

Output

perspective:
  id: material_health
  entity: Material
  score: 62
  polarity_balance:
    positive_signals: 4
    negative_signals: 3
    net: positive

Theses (reformed Hypotheses)

A Thesis is a free composition of signals and perspectives.

Key changes

• Can reference signals directly, perspectives, or both
• Can ask positive questions (“is this entity thriving?”)
• Supports polarity inversion (a negative signal as counter-evidence for a positive thesis)
• Verdict labels configurable: [confirmed, promising, inconclusive, not_observed]

Composition freedom

thesis_id: thesis_material_excellence
category: opportunity

evidence:
  - signal: signal_price_stability
    role: primary
    weight: 3
  - perspective: material_health
    role: supporting
    weight: 2
    polarity: inverted
  - signal: signal_negative_margin
    role: counter
    weight: 2

Signals are independent of perspectives. A thesis composes freely from both. The hierarchy is a network, not a chain.

                Thesis
               (free question)
              ╱      |       ╲
         Signal   Perspective   Signal
                  ╱    |    ╲
            Signal  Signal  Signal (same signal can appear directly AND through a perspective)

Verdicts (reformed Diagnoses)

A Verdict is a root cause judgment attached to a confirmed thesis.

Key changes

• diagnosis_id → verdict_id
• hypothesis_id → thesis_id
• root_cause_category stays (process_failure, system_failure, etc.)
• Can now explain positive outcomes (“why is this working well?”)

Findings Schema

CREATE TABLE signal_findings (
    finding_id        VARCHAR NOT NULL,
    tenant_id         VARCHAR NOT NULL,
    signal_id         VARCHAR NOT NULL,
    signal_version    VARCHAR NOT NULL,

    -- Signal properties (Sense 14)
    polarity          VARCHAR NOT NULL DEFAULT 'negative',
    score             DOUBLE NOT NULL DEFAULT 45.0,
    direction         VARCHAR,

    -- Impact (multi-dimensional)
    impact_value      DOUBLE,
    impact_unit       VARCHAR DEFAULT 'CHF',
    impact_dimension  VARCHAR DEFAULT 'financial',

    -- Entity
    entity_type       VARCHAR NOT NULL,
    entity_id         VARCHAR NOT NULL,
    time_bucket       VARCHAR,

    -- Evidence
    evidence          VARCHAR,

    -- Backward compatibility (computed)
    severity          VARCHAR,       -- derived from score + thresholds
    money_at_risk     DOUBLE,        -- abs(impact_value) when unit is currency
    health_score      DOUBLE,        -- perspectives only

    PRIMARY KEY (finding_id)
);

The Billion Dollar Fix

money_at_risk summed naively across duplicated findings → billions.

Rules:

1. Deduplicate before aggregating: one entity × one signal × one time_bucket = one observation
2. Aggregate scores, not impact: maps show average score, not summed CHF
3. Show net impact: positive + negative = net, not just “total risk”
4. Configurable aggregation: sum, weighted avg, worst-of, best-of — per context

Map Salon Integration

Channel	Maps to
x	time_bucket, entity_type, perspective
y	score (0-100), impact_value, signal_count
color	polarity (red/green/amber), score (gradient), direction
size	absolute impact, finding count

The zero line on y-axis separates opportunity (above) from risk (below).

Migration

Phase 1: Rename (current — Day 1)

Full rename across:

• Scripts (compilers, validators, registries)
• YAML artifacts (signals/, perspectives/, theses/, verdicts/)
• Contracts
• dbt models
• JinDesk routes and pages
• CLI commands
• Documentation

No new functionality — just the vocabulary change. Everything compiles and builds exactly as before, with new names.

Phase 2: Signal properties (Day 2)

• Add polarity, score, direction, impact_* to signal findings schema
• Existing signals: auto-populate from severity + money_at_risk
• Signal compiler: accept new YAML fields, emit new columns
• JinDesk: read new fields when present, fall back gracefully

Phase 3: JinDesk reads signals (Day 2-3)

• Findings pages show score + polarity
• Map Salon uses continuous score
• Color scale: polarity-aware (red ← 0 → green)

Phase 4: Positive signals + Perspectives (Day 3)

• First positive signals (price_stability, catalogue_completeness)
• Reform one assessment → perspective
• First opportunity thesis
• Green dots on the map

Phase 5: Cleanup (Day 4)

• Remove redundant signals (I/O weekly variants, stale duplicate)
• Fix billion-dollar aggregation
• Migration script for packs and live tenants
• Update synthetic data generator

Relationship to Other Senses

Sense	Relationship
Sense 7 (Price Lab)	Price stability = positive signal
Sense 10 (Computed Aggregates)	Score aggregation replaces naive SUM
Sense 11 (The Veil)	Signal visibility per identity
Sense 12 (The Mirror)	User preferences for signal display
Sense 13 (The Canvas)	Signal panels as building blocks

How this manifests in jinflow

Every signal you author lives as a YAML file in your tenant AFS at signals/signal_*.yaml, compiles to a dbt model via jin make, and produces a findings table JinDesk reads. The Val d’Oria demo runs the full pipeline on 16 active signals against 104K persons + 13K assignments — every finding you see is a real output of the chain this sense describes.

• In the app: Signal registry · Findings · Theses · Verdicts
• Authoring: Tutorial: Your First Build walks you from blank file to a working signal
• CLI: jin signal check validates the YAML · jin signal compile generates SQL · jin make builds the findings table

Status: shipped. The Signal / Perspective / Thesis / Verdict chain is the engine’s analytical spine and runs in every pack today.

Open Questions

1. Score computation: Signal YAML defines score_expression (SQL), compiler wraps it.

2. Impact units: Standardized base units (CHF, count, percent, days) with free-form display label.

3. Perspective membership: Declarative in the perspective YAML — the lens chooses its signals, not the other way around. A signal doesn’t need to know who’s looking at it.

4. Historical scores: Compute from KLS snapshots (time machine from Sense 5).

5. Thesis ↔ Perspective independence: A thesis can reference signals that belong to NO perspective. Perspectives and theses are independent composition axes over the same signal pool.

---

Numerical neighbors: ← Sense 13: The Canvas · Sense 14.2 — Typed Signals →