Sense 15: Observation and Explanation

Sense 15 · Folded in · Last touched 2026-08-20

Folded into Sense sense-15.

• last_verified: 2026-07-27
• superseded_by: sense_15.md

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

Superseded 2026-05-17. The current authoritative Sense 15 reference is sense_15.md, rewritten to reflect the diamond, the shipped Atelier, the substrate decision (YAML in AFS), and the named Sense 19 bridge. This file is preserved as the conceptual archive — the three-move CEO conversation, the strategic- not-operational rule, the two lifecycles, and the introduction of Contributing Factor all originated here. Read for the thinking; read sense_15.md for what we’re building.

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.

The CEO does not want to read signal_revenue_leakage fired 247 times. The CEO wants to hear “we observe money leaking in ward 3” — and then ask “show me” and “why?”.

Observation is what the human hears. Explanation is what the system owes them in return.

Status: proposed Author: the owner + Claude (conversation, 2026-04-05)

---

What pulled us in

After Sense 14 we have a clean machinery layer: signals produce findings, perspectives aggregate them, theses evaluate them, verdicts explain them, SMEbits supplement them. Five first-class terms, all well-named for analysts.

But the taxonomy has no top. There is no named artifact representing what a human being is actually trying to say about the business. Today the closest thing is “interpretations” — which is vague, derivative, unauthored, unstable, and indistinguishable from narratives, reports, or verdict prose. It’s a rendering with nowhere to live.

This matters for one specific reason: a CEO cannot enter the current system through its own front door. Every entry point — signals, findings, theses — presumes you already understand the machinery. JinDesk has no layer that speaks the language of the person who pays for the system.

A briefing never starts with metrics. It starts with a sentence. And that sentence has a structure the entire executive world recognizes:

1. What? — “We see money leaking in ward 3.”
2. Really? Show me. — “Here are 142 unbilled implants, here is the trend, here are the affected cost centres.”
3. Why? — “We believe it’s a workflow gap in the OR scheduling module. Confidence 0.73. the clinical SME flagged something similar in March — see her SMEbit.”

Three moves. Three answers. One conversation. The current system has all the ingredients for move 2 and move 3 — but move 1 is homeless.

Strategic, Not Operational (Critical Distinction)

Observations are strategic. They are not operational.

This is the single most important rule to communicate about Sense 15, and it must be stated up front so nobody misunderstands what an observation is for.

Level	Who it serves	How work happens	Artifact
Operational	Analysts, data engineers, domain users	Playground, filters, signals, findings browsing, drill-downs, what-if, dry runs, probe iteration	Signals + Findings (the machinery is the workspace)
Strategic	C-level, board, executive committee, SMEs communicating upward	Curated statements about the business, told as stories with a beginning/middle/end, accountable to a human author	Observations + Explanations

When an analyst is chasing a specific anomaly, testing a new detection rule, or drilling into why finding 4472 exists — they work directly with signals, findings, perspectives, and the Signal Builder. The machinery layer is their native habitat. Observations are not created or consumed at this level. Nobody signs an observation for “a weird duplicate in procedure 8392”. That’s a finding. Maybe a SMEbit if it’s worth remembering. Not an observation.

An observation is only created when an analyst, after operational work, decides: this pattern is significant enough for a CEO to care about. I am willing to sign my name to a statement of this pattern. It is a strategic fact about the business, not an operational detail.

This matters for three reasons:

1. It prevents the observation layer from becoming noise. If every operational finding becomes an observation, the CEO dashboard turns into the same endless row stream as /findings — and we lose the signal-to-noise ratio that makes observations valuable in the first place. Observations must be rare, deliberate, and high-stakes. A healthy system probably has 8–20 active observations at any time, not 200.

2. It protects operational productivity. Analysts need to iterate fast — test a signal, tweak a threshold, re-run, compare. They should never feel that every operational action has to be “promoted to an observation” to matter. The machinery layer stands on its own. It is fully usable without ever touching the observation system. An analyst can spend their entire workday in signals and findings and never need to think about observations.

3. It clarifies accountability. Because observations are strategic, they carry consequences: they influence board decisions, budget allocation, compliance posture. That’s why they require a signed author. Operational findings are routine evidence — no individual finding needs a signature, because no individual finding is a claim to the CEO.

The rule of thumb: If you’re asking “is this pattern real?” — you’re operating. Use the machinery. If you’re ready to say “this pattern matters enough that the CEO should know about it, and I stand behind that claim” — you’re strategic. Write an observation.

The Proposal

Introduce two new first-class concepts at the top of the taxonomy:

• Observation — a human-authored, human-accountable statement about the business, expressed in natural language, grounded in signals and findings.
• Explanation — the system’s answer to “show me” and “why?”, rendered at two clearly-labeled levels:
  • Explanation (evidence) — the factual drill-down that proves the observation exists. Data, charts, findings, trends. Not debatable.
  • Explanation (hypothesis) — the causal theory for why the observation exists. Theses, verdicts, SMEbit anchors. Explicitly labeled as belief, not fact.

The taxonomy flips from a pyramid rising toward insight into a pyramid descending from the human:

Observation                   ← what the CEO hears
├── Explanation (evidence)    ← "show me" → findings, charts, trends
└── Explanation (hypothesis)  ← "why?"   → theses, verdicts, smebits
    │
    └── signals → findings (machinery)

Everything below “Observation” becomes infrastructure in service of the observation. Signals are how we observe. Findings are the sensory stream. Theses/verdicts/SMEbits are candidate explanations. Observation is the system’s public voice.

Why Two Levels of Explanation

Today our theses and verdicts quietly blur the line between “we proved this” and “we think this”. When a verdict says “confidence 0.73 for root cause X”, it sounds authoritative. But the CEO deserves to know: is this an empirical fact or a working theory?

Sense 15 forces honesty:

Level	Claim	Example
Evidence	”This is observable in the data."	"142 implants were used in cases that had no corresponding billing line. Total exposure: CHF 340K. Trend is stable across 12 months.”
Hypothesis	”This is our working theory."	"We believe the cause is a process gap between OR completion and billing entry. Confidence 0.73, based on condition-signal thresholds and a related SMEbit from the clinical SME (March 2026). This is a hypothesis, not a proof.”

This is adult language. CEOs hate false certainty more than they hate uncertainty. “Here’s what we know, here’s what we think, here’s the gap” is the correct register for executive briefings.

What This Solves

1. The interpretations problem. Interpretations were trying to be the CEO-readable face of findings, but they had no identity, no author, no stability, and no position in the taxonomy. Observations replace them cleanly. Same intent, better name, proper place.

2. The entry point problem. A CEO can open /observations and read the system like a morning newspaper — no vocabulary required. Drilling into any observation reveals first its evidence (move 2), then its hypothesis (move 3). The five existing terms become analyst vocabulary, not executive vocabulary.

3. The accountability problem. Today, no artifact in the system has a human being’s name on it as the accountable author. Signals, theses, verdicts — these are collectively owned YAML files. But a statement to the CEO needs a person standing behind it. Observations carry that signature.

4. The “story vs. event” problem. Findings are events. Observations are stories. Executives do not want event streams — they want stories about the business with a beginning, a middle, and (sometimes) an end. Sense 15 gives the system a place to tell stories.

Authorship: Fully Accountable

An observation is owned by one human being who is fully accountable for it.

This is a non-negotiable design choice. It is not auto-generated. It is not anonymous. It is not collective. One person, one name, one signature. If the observation is wrong, there is someone to ask. If it is well-framed, there is someone to credit.

This does not mean the authoring work is unassisted. The system can:

• Scan recent findings and propose candidate observations (“would you like to promote this pattern to an observation?”)
• Pre-populate drafts with suggested text, time windows, source signals
• Flag stale observations whose underlying findings have materially changed
• Suggest related SMEbits and theses as explanation seeds

But the final act of writing, editing, and signing the observation is human. The author’s name, role, and date are part of the observation record, forever.

This also clarifies a trust chain that was previously muddled:

Artifact	Authored by	Signed?
Signal	Analyst / data engineer	Collective (YAML in git)
Finding	Machine	No — it’s an event
Thesis	Business analyst	Collective (YAML in git)
Verdict	Rule engine	No — it’s a judgment computed from evidence
SMEbit	Subject matter expert	Yes — SMEbits already carry provider metadata
Observation	Human curator	Yes — fully accountable, not delegable

Observations and SMEbits are the two artifacts in the system that carry real human accountability. Both are on the communication boundary between the machinery and the humans who act on it. That is not a coincidence.

Lifecycle: Observations Travel, but Never Die

Observations are not events. They are stories that persist across time. A good observation might first appear in March, worsen through the summer, be investigated in September, and quietly retire in December when the underlying process is fixed. But six months later the same pattern could recur — and the observation should come back, with its full history visible.

Lifecycle states

   draft                  — being authored, not yet visible
     │
     ▼
   active                 — currently visible, tracked, may update
     │
     ▼
   dormant                — no longer visible on the dashboard,
     │                      but preserved with full history
     │
     ▼                      (can reactivate if the pattern recurs)
   resolved               — explicitly closed; root cause addressed
     │
     ▼
   superseded             — replaced by a newer observation that
                            tells the same story better or broader

Key principles:

1. An observation never truly dies. Once authored and activated, it lives in the system forever. It can become invisible (dormant, resolved, superseded) but its history, its evidence, its explanations, and its author’s name remain queryable.

2. Reactivation is a first-class operation. If a dormant or resolved observation’s underlying pattern recurs, the system notices and prompts the current curator to reactivate it. The observation now has a second chapter: “first observed in March 2026, resolved in December 2026, reactivated in April 2027 following a workflow regression.”

3. Supersession is how observations evolve. If a later curator realises the original framing was too narrow or too broad, they author a new observation and mark the old one as superseded_by. The old observation stays visible in the history; the new one becomes active. Readers can always walk the supersession chain backwards.

4. Observations have a time window, not a timestamp. An observation is about a period of time: “the past 12 months”, “Q3 2025”, “since the March migration”. The window is part of the observation, not metadata.

5. Observations update, but carefully. Each update is a new version with a diff and a reason. “2026-06-01: severity upgraded from medium to high as exposure grew to CHF 480K.” The author’s name on each revision may be the same or different; the history preserves both.

Infrastructure: Notes as the Substrate

Observations are built on top of the existing notes system, not as a new storage layer.

This is the right move because notes already carry exactly the primitives observations need:

• Author — notes have a human owner
• Timestamp — notes have creation and update times
• Content — notes store markdown/prose
• Context — notes can attach to entities, signals, findings, reports
• History — notes already support an edit/audit trail
• Lifecycle — notes already have a “state” concept
• Replies and threads — notes support conversation, which is exactly how observations should evolve over time (curator posts an observation, analysts reply with supporting findings, SMEs reply with context)

An observation is a note with structure. Specifically, it is a note that:

• Has kind: observation (distinguishing it from a general note, a comment, a task)
• Has a stable observation_id (independent of the note’s internal ID, so it can survive edits)
• Has a time_window field
• Has a lifecycle_state field
• Has a typed set of anchors: to signals, perspectives, theses, verdicts, findings, SMEbits, and other observations
• Has two embedded explanation sections: evidence (auto-rendered) and hypothesis (curator-selected)

No new database table. No new storage mechanism. Just a new kind of note, with a richer schema and its own rendering. All of the notes infrastructure — threading, replies, history, mentions, author accountability, tenant isolation — is reused for free.

This also means observations are naturally reply-able, discussable, and collaborative. A curator posts an observation. An analyst replies with a new finding that reinforces it. A CFO leaves a comment asking for a specific drill-down. An SME attaches a SMEbit explaining a contextual factor. The observation grows, over days and weeks, into a living document of how the organisation has understood this particular pattern of the business — with every contribution timestamped and signed. That is institutional memory on rails.

Data Model Sketch

# observations/obs_2026_q1_material_leakage.yaml   (or equivalent notes record)

observation_id: obs_2026_q1_material_leakage
kind: observation
lifecycle_state: active              # draft | active | dormant | resolved | superseded

author:
  name: the owner Käfer
  role: Lead Analyst
  signed_at: 2026-04-05T10:30:00Z

time_window:
  start: 2025-04-01
  end: 2026-03-31
  label: "Past 12 months"

title:
  en: "Material usage not matched by billing in OR wards"
  de: "Materialverbrauch ohne Rechnungszeile in OP-Stationen"
  fr: "Consommation matériel sans facturation dans les blocs opératoires"

summary:
  en: |
    Over the past 12 months we observe a persistent gap between OR material
    usage and corresponding billing events. Exposure to date: CHF 340K.
    The gap is concentrated in wards 3, 5, and 7, and has been stable —
    not growing, not shrinking. This is not a recent regression;
    it is a structural leak.
  de: |
    (...)

# Explanation 1: evidence (auto-rendered from anchors)
evidence:
  anchors:
    - signal_id: signal_revenue_leakage
      role: primary
    - signal_id: signal_billing_gap
      role: supporting
  findings:
    count: 247
    total_money_at_risk: 340000
    affected_entities: 142
  trend: "stable"           # stable | worsening | improving | volatile
  charts:
    - kind: time_series
      metric: money_at_risk
      bucket: month

# Explanation 2: hypothesis (curator-selected)
hypothesis:
  anchors:
    - thesis_id: thesis_revenue_leakage_unbilled
      role: primary
    - verdict_id: verdict_billing_workflow_gap
      confidence: 0.73
    - smebit_id: smebit_or_paper_tracking
      role: context

  statement:
    en: |
      We believe the cause is a workflow gap between OR completion and
      billing entry — specifically, paper-based tracking of high-value
      implants that never reaches the billing system because the manual
      handoff is skipped under time pressure. This is a hypothesis,
      not a proof. the clinical SME flagged a similar pattern in March 2026
      (see smebit_or_paper_tracking).

lifecycle_history:
  - state: draft
    at: 2026-04-05T09:00:00Z
    by: mig
  - state: active
    at: 2026-04-05T10:30:00Z
    by: mig
    note: "signed and published to CEO dashboard"

supersedes: null
superseded_by: null

What Happens to the Existing Taxonomy

Sense 15 adds a layer; it does not remove anything except the poorly-positioned “interpretations” concept.

Term	Role after Sense 15
Signal	Unchanged — mechanism for observing
Finding	Unchanged — atomic sensory event
Perspective	Unchanged — aggregator / lens
Thesis	Unchanged — business question, lives in hypothesis layer
Verdict	Unchanged — root cause theory, lives in hypothesis layer
SMEbit	Unchanged — expert knowledge, can anchor in either explanation level
BitBundle	Unchanged — curator’s narrative grouping
Interpretation	Removed — absorbed into Observation (evidence section)
Observation	NEW — top of taxonomy, human-authored, signed
Explanation	NEW — rendering concept with two levels (evidence, hypothesis)

C-Level Reading Experience

Imagine a CEO opening JinDesk for the first time:

1. Lands on /observations — the home page.
2. Sees 8–12 active observations, each a one-line title with a short summary and a signal count badge.
3. Clicks one. Sees:
   • Title and summary in their language.
   • Author name + date (“signed by the owner Käfer, Lead Analyst, 2026-04-05”).
   • “Show me” button → expands Evidence section with findings, a chart, and a drill-down table.
   • “Why do you think so?” button → expands Hypothesis section with thesis reasoning, verdict confidence, and SMEbit context.
   • Thread of replies from analysts and SMEs, chronological.
4. At the bottom: “Last updated 3 days ago by the owner. History →”.

Zero vocabulary. Three clicks from “what?” to “why?”. An executive can be productive in JinDesk in five minutes, without ever hearing the word “signal”.

Open Questions

1. Where do observations live in the AFS? New top-level observations/ directory with YAML files, or entirely inside the notes system with no filesystem presence? (My instinct: notes system. File-based would duplicate the lifecycle mechanics notes already provide.)

2. Multi-tenant and cross-tenant observations. Can an observation span multiple tenants? (“We observe declining revenue across all three hospitals in the network.”) Probably yes, with scope: { tenants: [...] } — but this is an extension, not a Sense 15 requirement.

3. Localization of author-written prose. Observations are tri-lingual today (EN/DE/FR). Do we require all three from the human author, or do we allow primary language + on-demand machine translation with an explicit “auto-translated” label?

4. Access control. Observations are visible to the CEO. Are all observations visible to the CEO, or do curators choose a visibility level (internal, executive, board)?

5. The auto-proposal engine. How aggressive is the system in suggesting observation drafts? Daily digest? Inline prompts on the findings page? Background worker that watches for pattern changes and DMs the curator?

Implementation Phasing (later document)

A follow-up implementation paper should cover:

• Notes schema extension for observation records
• /observations list and detail pages
• /observations/new author flow (with auto-proposal assistance)
• Migration of existing interpretations (if any are worth preserving) into observations
• Sidebar nav: promote “Observations” to the top of the Model section, above signals
• Integration with reports (observations become the narrative spine of executive summaries)
• Removal of the /interpretations route and its capability

---

Addendum (2026-04-05): Validation, Explanation, and the Birth of “Contributing Factor”

The original proposal introduced Observation and Explanation as the two new top-layer concepts, with Explanation wearing two hats — one labeled (evidence) and one labeled (hypothesis). In conversation we realised this is a smell: using the same word for two different things with qualifiers asks the reader to carry a distinction in their head that the words themselves do not support. This addendum sharpens the terminology and adds a new concept — contributing factor — that gives the system, for the first time, a first-class atomic unit for reasoning.

The sharper vocabulary

Match everyday language. When a CEO asks “show me” or “is this real?”, they are not asking for an explanation — they are asking for validation. When they ask “why?”, that is explanation. The words should do the work.

The three-move CEO conversation (revised):

1. What? → Observation
2. Is this real? Show me the data. → Validation
3. Why is this happening? → Explanation (composed of contributing factors)

The honesty gap is preserved, but now it lives in two different words instead of two flavors of the same word:

Layer	Claim	Character	Example
Validation	”This is observable in the data.”	Empirical, not debatable	”142 implants used in unbilled cases. CHF 340K exposure. Trend stable across 12 months.”
Explanation	”This is our working theory of why.”	Theoretical, explicitly a belief	”We believe the cause is a workflow gap in OR scheduling, aggravated by a catalogue staleness issue and a training regression after the March migration. Confidence: medium. Signed by three contributors.”

Validation is the empirical wall beneath the observation. Explanation is the theoretical ceiling above. An observation without validation is a claim without proof. An observation without an explanation is an honest “we see it, we don’t yet know why.”

The updated taxonomy

Observation                         ← what the CEO hears (strategic, signed, accountable)
│
├── Validation                      ← "is this real? show me"
│   └── findings, charts, trends, drill-downs (from the machinery layer)
│
└── Explanation                     ← "why?" (theory, composed)
    ├── Contributing Factor 1       ← anchored to signal(s)
    ├── Contributing Factor 2       ← anchored to thesis + verdict
    ├── Contributing Factor 3       ← anchored to SMEbit
    └── Contributing Factor 4       ← free-form curator judgment

Observation stays at the top, signed, strategic. Validation is empirical and auto-rendered from the machinery. Explanation is human-curated theory. Contributing factors are the atoms of explanation.

Contributing factor: a new first-class concept

An explanation is no longer a monolithic block of prose. It is a composition of contributing factors, where each factor is a small, independently-reasoned claim about one cause that helps account for the observation.

Each contributing factor has:

• A short natural-language statement (“OR staff skip the paper handoff under time pressure”)
• An origin — anchored to a signal, thesis, verdict, SMEbit, or authored freely as curator judgment
• A role weight — is this a primary driver, a secondary influence, a modifier, or a counter-factor (something that would push the observation in the opposite direction if it weren’t present)?
• A confidence level — how strongly do we believe this factor is actually causal?
• Its own author and signing timestamp, independent of the observation’s author

Why contributing factors matter

1. Real root-cause analysis is never monocausal. An observation about revenue leakage usually has multiple contributing factors: a workflow gap, a catalogue staleness issue, a training regression, a regulatory change. Today our system can express exactly one verdict with one root-cause category per confirmed thesis. That is a severe simplification of how causation actually works in organisations. Contributing factors fix this — the explanation is a weighted portfolio of causes, not a single chosen cause.

2. Distributed authorship becomes natural. The observation author signs the observation. But the clinical SME (a clinical lead) can contribute one factor from her SMEbit; an SAP consultant can contribute another from a thesis investigation; the data team can contribute a third from a signal pattern they found. Three people, three signatures, one coherent explanation, each contribution separately accountable. This is how real institutional knowledge forms — many hands, one story. Today our system has no shape for this; SMEbits stand alone and verdicts are rule-computed. Contributing factors bridge the gap.

3. Explanations can grow over time without invalidating the observation. If in May we discover a fourth contributing factor, we add it to the existing explanation without touching the observation itself or its earlier factors. The observation is a stable strategic fact (“we observe X”); the explanation is a living theory that matures as evidence accumulates. Contributing factors are append-only by default; supersession works at the factor level, not the observation level.

4. It creates a clean hook for the honest “we don’t know yet” case. An observation can exist with zero contributing factors. “We observe a 12-month decline in top io-coefficients. We do not yet have a working theory for why. Investigation in progress.” That is a perfectly valid observation — and today our system has no way to say it, because a hypothesis-less thesis feels like an empty form. With contributing factors, an empty explanation is meaningful: it signals that the curator has validated the observation but is not yet willing to guess at causes.

5. Counter-factors preserve intellectual honesty. A contributing factor can be marked as counter — something that works against the observation’s direction. This forces the curator to state what would make them change their mind, which is the mark of a serious theory. “The OR volume has grown 8% in the same period, which would normally increase the leakage we observe. So the underlying rate is worse than it looks.” That’s a counter-factor, and it’s the kind of nuance that elevates a theory from “opinion” to “reasoned analysis”.

Contributing factor data model sketch

# Embedded inside an observation's explanation section

explanation:
  state: "active"              # draft | active | under_review | settled
  last_updated: 2026-04-15T14:22:00Z

  contributing_factors:
    - id: cf_or_paper_handoff_skip
      statement:
        en: "OR staff skip the manual billing handoff under time pressure."
        de: "(...)"
        fr: "(...)"
      role: primary             # primary | secondary | modifier | counter
      confidence: 0.73           # 0.0 - 1.0
      anchors:
        - kind: smebit
          id: smebit_or_paper_tracking
        - kind: signal
          id: signal_missing_billing_handoff
      author:
        name: Dr. Jane Doe
        role: Clinical Lead
        signed_at: 2026-04-05T11:15:00Z

    - id: cf_catalogue_staleness
      statement:
        en: "High-value implant entries in the catalogue have drifted from reality since the March migration, causing billing lookup failures."
      role: secondary
      confidence: 0.55
      anchors:
        - kind: thesis
          id: thesis_stale_catalogue
        - kind: verdict
          id: verdict_catalogue_data_quality
      author:
        name: Alex Weber
        role: SAP Consultant
        signed_at: 2026-04-10T09:30:00Z

    - id: cf_or_volume_increase
      statement:
        en: "OR volume has grown 8% over the period, so the underlying leakage rate is actually worse than the raw numbers suggest."
      role: counter
      confidence: 0.80
      anchors: []               # purely curator-authored, no machinery anchor
      author:
        name: the owner Käfer
        role: Lead Analyst
        signed_at: 2026-04-12T16:00:00Z

Open questions for the follow-up conversation

The “contributing factor” concept opens design questions that deserve their own dedicated think. Noting them here as threads to pick up later:

1. Separate storage or embedded? Is a contributing factor a new storable artifact with its own identity (queryable across observations), or is it just a structured record embedded in an observation’s notes document? Leaning embedded for simplicity, but if SMEs want to maintain a personal portfolio of “factors I have contributed across all observations”, that argues for independent identity.

2. Multi-observation reuse. Can the same contributing factor belong to multiple observations? The “OR paper-handoff skip” might plausibly contribute to three different observations: one about revenue leakage, one about billing accuracy, one about audit risk. If yes, contributing factors need independent IDs and a many-to-many relationship with observations.

3. Relationship to SMEbits. Contributing factors and SMEbits feel related but distinct. A SMEbit is a piece of expert knowledge about the world (“staff skip handoffs”). A contributing factor is a claim that this piece of knowledge is a cause of a specific observation. One SMEbit might seed many contributing factors in different observations. A contributing factor might cite a SMEbit without being one. This distinction wants more thought.

4. How are contributing factors proposed? The system could auto-propose candidate factors by walking the signals/theses/verdicts/SMEbits anchored to the observation and summarising each. The curator then edits, accepts, rejects, or writes new ones by hand. Or the curator starts from a blank sheet. Or some mix.

5. Confidence calibration over time. Contributing factors carry a confidence level. Who updates it, and when? If new evidence accumulates that strengthens or weakens a factor, does the system prompt the author, or does it just append a note? (This is analogous to how scientific literature treats confidence in hypotheses — something to steal from.)

6. Counter-factor weighting in the overall explanation. If an explanation has three primary factors and one strong counter-factor, how does the reader synthesise them? Do we render a “net confidence” number, or keep it purely qualitative and let the reader judge? Strong preference for the latter — summary numbers hide the actual reasoning.

Summary of the refinement

Original Sense 15	Refined Sense 15
Observation	Observation (unchanged)
Explanation (evidence)	Validation
Explanation (hypothesis)	Explanation, newly composed of Contributing Factors
—	Contributing Factor (new first-class concept)

The refinement does not change the architecture, the notes infrastructure, the authorship model, the lifecycle, or the strategic-vs-operational rule. It only sharpens the vocabulary and introduces a new atomic unit for reasoning. Everything else in the original paper stands.

---

The one sentence summary: After Sense 14 we gave the machinery its proper vocabulary. Sense 15 gives the humans theirs — Observation for what we see, Validation for proving it real, and Explanation (built from Contributing Factors) for reasoning about why.

---

Addendum (2026-05-05): The Hourglass, Two Lifecycles, and the Bridge to Simulation

Vocabulary note (2026-05-06). The hourglass framing in this addendum has been superseded by the jinflow — the diamond diagram with Understanding at the centre and Strategy / Analysis / Expertise / Action around it. See docs/design/the_jinflow.md. The substantive content of this addendum — the two truth-state lifecycles, the inconclusive / insufficient distinction, and the bridge to Sense 19 — remains valid; only the geometric metaphor is replaced. The hourglass and pyramid metaphors are retired.

The April 5 refinement clarified vocabulary (Validation, Explanation, Contributing Factor) and gave reasoning a first-class atomic unit. A month later, while drafting the inspire training tenant, three further sharpenings became necessary. None change the architecture — but each tightens a concept that was implied but not stated, and the third draws the bridge to Sense 19 explicitly.

1. The metaphor: hourglass, not pyramid

The original paper describes the system as a pyramid descending from the human (“Observation at the top, machinery at the base”). The April addendum kept this metaphor. After working through the inspire welcome note, the metaphor showed strain in three places:

• Sense 14 made Signals polarity-neutral. A pyramid narrows toward “truth at the top”. But signals can be positive, neutral, or negative; theses can be confirmed or not_observed — both meaningful. The narrowing assumption is wrong.
• Sense 15 inverted the top. Observations are claimed first (top-down, outside-in: “we suspect we’re losing money on generics”), then validated against the operational machinery, then explained via contributing factors. The pyramid says evidence assembles into verdicts. Sense 15 says claims dispatch the machinery to find evidence. Same parts, opposite direction.
• Subject Matter is orthogonal, not vertical. Dossiers, Statements, and Checks sit beside the analytical machinery — codified expert knowledge that anchors decisions at every level. The pyramid has no axis for this.

The right metaphor is the hourglass:

                      Strategic — outside-in, top-down
              Observation (status: suspected → validated → … )
                          ↓
                     Explanation
                          ↓
                Contributing Factors
                          ↓
                  Recommended Actions  (forward to Sense 19)

      ─────────  Meeting Point — Entity + Contract  ─────────
                    Findings   ·   Verdicts

                      Operational — inside-out, bottom-up
                          Theses
                          ↑
                       Perspectives
                          ↑
                        Signals
                          ↑
                  Gold (Bronze → Silver → Gold)

  Subject Matter (Dossiers · Statements · Checks)
  surrounds both halves orthogonally — the glass itself

Two flows converge at the neck (Entity + Contract):

• Operational flow rises: evidence assembles into Findings and Verdicts.
• Strategic flow descends: Observations dispatch the machinery to test against those same Findings and Verdicts.

Subject Matter wraps both halves — the codified knowledge that anchors what an article means, what a cost centre is for, when an exception is expected. Dossiers, Statements, and Checks belong nowhere on the vertical axis because they apply at every level.

The pyramid is not retired entirely. It still describes the operational machinery alone — Signal → Perspective → Thesis → Verdict, narrowing from sensory stream to judgment. Local use is fine. But for jinflow as a whole, the pyramid hides the second directionality and the orthogonal Subject Matter axis. The hourglass shows them.

The inspire training tenant uses the hourglass on its welcome note. Subsequent design docs should mirror the convention.

2. Two lifecycles, not one

The original paper describes one lifecycle: draft → active → dormant → resolved → superseded. That lifecycle is editorial — it tracks whether the curator is actively maintaining the observation, whether it’s been published, whether it’s been retired.

But an observation has a second, distinct lifecycle that the original paper conflated: its truth state. Is the claim empirically true? The data may not yet have been examined. Or the data may agree. Or the data may contradict. Or the data may be inconclusive. Or the situation may have changed and resolved itself. These states have nothing to do with whether the curator is maintaining the observation; they’re about what the world says.

The two lifecycles coexist:

Lifecycle	Concerns	States
Editorial (curator-driven)	Is the curator maintaining this observation?	draft → active → dormant → resolved → superseded
Truth state (machinery-driven)	What does the data say about the claim?	suspected → validated → refuted → inconclusive → resolved

Truth-state lifecycle

  suspected         ← claim authored; data not yet checked, or signals
     │                not yet set up to evaluate it
     │
     ▼  (validation runs)
  ┌────────────────────────────────────────────────┐
  │                                                │
  ▼                                                ▼
  validated         refuted        inconclusive   resolved
  Data agrees       Data           Machinery     Action taken;
  (signals fire,    contradicts    ran but       observation
  theses confirm)   (counter-      results don't closed by
                    evidence       clearly       the operator
                    dominates)     support or
                                   refute

Each truth state means a different thing to the operator:

Status	Meaning	What to do
suspected	Claimed but not yet validated. The default after authoring.	Run validation.
validated	Findings + theses corroborate the observation.	Move to Explanation. Build Contributing Factors.
refuted	Data contradicts the claim. The Explanation explains why the claim was wrong.	Equally valuable as validated. Document the refutation.
inconclusive	Machinery ran, but evidence is mixed or magnitude too small to decide.	Sharpen the claim, add Contributing Factors, or accept ambiguity.
resolved	Action taken; the world has moved on. The observation is closed by the operator, not the data.	Archive as institutional memory.

suspected is a first-class state, not embarrassment. C-level walks in with hunches. Most BI tools have no shape for “we suspect this but haven’t checked yet”. jinflow gives that suspicion a typed home — and an explicit obligation to validate it.

inconclusive is also a first-class state. Most BI tools pretend everything is yes or no. jinflow says: sometimes the world doesn’t answer cleanly. That’s an honest result, worth recording.

The two lifecycles do not interact at the model level — an observation can be active (editorial) and inconclusive (truth state) simultaneously, meaning “the curator is maintaining it, the data hasn’t decided yet”. They render as two separate badges in JinDesk.

3. inconclusive (Observation) ≠ insufficient (Thesis)

A subtle but important distinction. Both terms describe a kind of “we couldn’t decide”, but they live at different layers and have different remedies.

	insufficient (Thesis)	inconclusive (Observation)
Layer	Operational (bottom of hourglass)	Strategic (top of hourglass)
What it reports	The machinery couldn’t reach a verdict.	The claim couldn’t be answered from the evidence we have.
Failure mode	Evidence pipeline incomplete — signals didn’t fire, data layer missing, signal coverage gaps.	Evidence pipeline ran fine but results don’t clearly support or refute.
Honest translation	”We couldn’t run the test."	"We ran the test. The world didn’t answer.”
Remedy	Build more signals, fix data quality, extend coverage.	Refine the claim, add Contributing Factors, or accept the question isn’t decidable today.
Who acts on it	Pack/tenant author (instrument the machinery better).	Observation author (sharpen the question or accept ambiguity).

A concrete pair:

Thesis: thesis_revenue_leakage_unbilled → insufficient signal_revenue_leakage produced 0 findings — not because there’s no leakage, but because bronze_billing_events was empty for this tenant. The thesis literally couldn’t be evaluated. Action: get billing data flowing.

Observation: “We’re losing money on generic substitutions” → inconclusive The relevant signals fired (signal_negative_margin: 411K findings; signal_billing_below_internal_price: 401K). The relevant theses evaluated. But Contributing Factors split: pricing-side evidence supports the claim, procurement-side evidence contradicts it. Action: split the observation into two narrower claims, or accept that “generic substitutions” is too coarse a unit to resolve.

insufficient can feed into inconclusive, but they’re not synonyms. An observation with five underlying theses, three confirmed and two insufficient, might still come out inconclusive — the strategic conclusion remains undetermined because the picture is incomplete. Conversely, all-confirmed theses can still produce an inconclusive observation if their findings point in opposite directions on the strategic question.

The two terms must coexist verbatim in the system. Mixing them up sends operators chasing pipeline gaps when the actual problem is a fuzzy claim, or vice versa.

4. The bridge to Sense 19: Recommended Actions and the Simulation handoff

The April 5 addendum left the strategic layer ending at Contributing Factors — the curator reasons about why the observation exists. The implicit next move was “now do something about it”, but the original paper had no name for this artifact. Sense 19 (The Simulation, 2026-04-17) names it: Suggestion.

The complete journey, top to bottom, now reads:

Observation                  ← what the CEO hears
    ↓
Validation                   ← "is this real? show me"  (auto-rendered from machinery)
    ↓
Explanation                  ← "why?"  (curator-authored)
    ↓
Contributing Factor 1, 2, 3  ← composed atoms of explanation
    ↓
─────── Sense 19 begins here ───────
    ↓
Suggestion                   ← "what should we do?"  (human-readable recommendation)
    ↓
Intervention                 ← "how exactly?"  (deterministic AFS edit)
    ↓
Scenario                     ← "what would the world look like?"  (AFS branch)
    ↓
Simulation                   ← "what happens?"  (build, compare, decide)

A Recommended Action in everyday language is what becomes a Suggestion in Sense 19’s typed form. The two are the same artifact named in two registers — the prose-level prompt to act (“we should tighten the revenue-leakage threshold to 5%”) and the system-level concept that can be turned into an Intervention, applied to a Scenario, run through a Simulation, and adopted (or not) based on what the simulated world looks like.

Sense 15’s contribution to this chain is the Explanation that justifies a Suggestion. Without it, suggestions are unsourced opinions; with it, every Suggestion can trace back through Contributing Factors → Explanation → Validation → Observation, and every step in that chain has an author and a signature. That trace is what makes a Suggestion adoptable rather than ignorable.

Where Sense 15 ends:

• The Observation is validated (or refuted, or inconclusive).
• The Explanation has one or more Contributing Factors.
• One or more Suggestions emerge from the Contributing Factors (the curator authors them, or the system proposes candidates from the Verdicts and Subject Matter anchored to the Contributing Factors).

Where Sense 19 begins:

• Each Suggestion can be turned into an Intervention.
• Interventions assemble into a Scenario.
• The Scenario is built (a full jin make on the scenario AFS branch).
• The Simulation result is compared to production via the Diff Loupe.
• The operator decides: adopt, archive, or iterate.

The two senses are independent — Sense 15 stands without Sense 19 (an Observation with Contributing Factors is already useful), and Sense 19 stands without Sense 15 (a Suggestion can come from a Verdict or Subject Matter directly). But together they close the loop from “we suspect this” to “we modeled the impact and acted”. That loop is the jinflow Experience the user is meant to feel.

The full noun topology

How to read it:

• Five colour bands, five conceptual layers. Strategic (purple) descends from above. Operational (teal) rises from below. They meet at the Meeting Point (amber): Findings and Verdicts, the currency both directions traffic in. Action (pink) extends out from Contributing Factors as the path forward — through Suggestion, Intervention, Scenario, Simulation. Subject Matter (yellow) wraps everything as the codified expertise that anchors decisions at every layer.

• The two directionalities are explicit. Operational reads bottom-up: data → Signal → Perspective + Thesis → Verdict. Strategic reads top-down: Observation → Validation (asking “is this real?” of the machinery) → Explanation → Contributing Factors. Both flows produce or consume Findings and Verdicts at the Meeting Point.

• Contributing Factors are the joinery. They cite Verdicts (operational evidence), Theses (operational claims), Subject Matter (codified expertise), and they author Suggestions (the bridge to Sense 19). Most cross-band edges in the diagram pass through Contributing Factors, which is why they’re a first-class atomic unit.

• The action chain is grounded, not free-standing. A Suggestion in Sense 19 has a name and an author because it traces back through Contributing Factors → Explanation → Validation → Observation, every step signed and timestamped. That’s what makes it adoptable rather than ignorable.

• The diagram doesn’t try to show feedback loops. A Simulation result can inform a new Observation; a confirmed Verdict can prompt a new strategic Observation; a fresh Statement can sharpen an existing Contributing Factor. All true, none drawn here, deliberately. The forward flow is the spine; the loops are everyday operation. Adding them visually obscures the spine.

Summary of the second addendum

Concept	Status before	Status after
Pyramid metaphor	Load-bearing in original paper	Retired as central metaphor; Hourglass replaces it for jinflow as a whole; pyramid kept locally for the operational machinery alone
Lifecycle of an Observation	One: draft → active → dormant → resolved → superseded	Two: editorial (unchanged) + truth state (suspected → validated → refuted → inconclusive → resolved)
inconclusive vs insufficient	Implicit, sometimes conflated	Explicit distinction. Operational vs strategic, pipeline gap vs claim ambiguity, different remedy and different operator
Bridge to Sense 19	Unnamed; observation chain ended at Contributing Factors	Named explicitly: Recommended Action in prose = Suggestion in Sense 19’s typed form. Complete journey from Observation through Simulation now traceable end to end

Architecture, infrastructure (notes-as-substrate), authorship model, and the strategic-vs-operational rule are all unchanged from the April 5 addendum. The hourglass, the two lifecycles, the inconclusive/insufficient distinction, and the Sense 19 bridge are all sharpenings on top.

---

Numerical neighbors: ← Sense 15 — Observation (entity with facets) · Sense 16: P2P2P — Peer-to-Peer-to-People →