Sense 15 — Observation (entity with facets)

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

• last_verified: 2026-07-27
• supersedes: sense_15_observation_and_explanation.md

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

The Observation is the entity. Explanation and Contributing Factor are facets it carries — not peer sub-entities, not a flat trio. An Observation is a signed notice, with state; the facets describe its why (Explanation) and what grounds it in Understanding (Contributing Factor). One Observation can carry zero, one, or many Explanations; an Explanation is composed of Contributing Factors; Contributing Factors are reusable atoms (m:n) with their own files.

Status: shipped Authors: the owner + Claude (rewrite, 2026-05-17; V2 reframe, 2026-06-27) Reference: the_jinflow.md — the five-name model. This doc unfolds the Observations name into the Observation entity and the facets it carries. The parallel to Data’s thesis tier is structural: an Observation asks “is X the strategic story?” the way a Thesis asks “is X happening in the data?” — same metapattern, two altitudes.

---

The structural premise

Sense 15 doesn’t introduce a new shape. It unfolds an existing one at a higher altitude.

	Data name · Thesis tier (Sense 14)	Observations name (Sense 15)
The proposition	Thesis	Observation
About	The data	The environment the tenant operates in
Question posed	”Is X happening in the data?"	"Is X true in the world?”
Truth states	confirmed / plausible / not_observed / insufficient	suspected / validated / refuted / inconclusive / resolved
Validated by	Signals — the only valid source of evidence	Anything that convinces stakeholders — signals, surveys, citations, expert testimony, regulatory filings, notes
Gates what’s above it	Confirmation lets Verdicts fire	Validation lets Explanations be authored
Authored by	Analysts	Executives, board, deans, named curators
Composes evidence into	One Verdict (root-cause judgement)	One or more Explanations (competing theories)
Atomic citation unit	Verdict’s conditions[] entries	Contributing Factors — first-class, m:n with Explanations

Theses and Observations are the same metapattern at different altitudes — a proposition, a truth state, anchors to evidence, an explanation of why. But they are not the same artifact. Their sources diverge sharply: a Thesis can only be validated by data; an Observation can be validated by anything a curator decides is convincing. They are meant to walk toward each other: Data ascends from rows toward strategic relevance, Observations descend from the environment toward data-checkable propositions. When they meet at Understanding — when an Observation cites a Thesis among its anchors, when a Thesis surfaces in an Observation’s Used by panel — the encounter is the strategic payoff. They don’t have to meet, but when they do, the executive’s notice is corroborated by the analyst’s evidence (or refuted by it), and the analyst’s pattern is lifted to strategic altitude.

Four consequences fall out of this framing.

1. Validation widens beyond the Understanding band. The April Sense 15 doc framed Validation as “the Understanding band ratifying the Observation”. That’s the special case where evidence happens to be internal. The general case: validation is the body of evidence presented to stakeholders to convince them the Observation is real. Anchor kinds therefore include signal / perspective / thesis / verdict / finding / smebit / dossier / observation (internal) AND external / note / survey / citation (external) — the latter carrying URL / source / date / author fields instead of an internal id.

2. No origin field. An Observation is always about the environment, regardless of what sparked it. Whether the curator was sitting on a hunch or saw a Verdict in the morning dashboard is process trivia, not a structural distinction. The truth-state lifecycle (suspected → validated / refuted / inconclusive → resolved) carries everything the schema needs to know.

3. Observation : Explanation is 1:n. Multiple competing or complementary theories can co-exist under one Observation. “Here’s the SAP consultant’s theory; here’s the clinical lead’s theory; here’s the CFO’s theory.” Each Explanation has its own state (draft / active / settled), its own author chain, its own list of Contributing Factors. The honest plural beats a forced choose-one.

4. Explanation : Contributing Factor is m:n. CFs are first-class. A factor like “OR staff skip the manual handoff under time pressure” plausibly contributes to several Observations — revenue leakage, billing accuracy, audit risk. Contributing Factors are reusable atoms with their own files at <afs>/contributing_factors/cf_*.yaml, their own global ids, their own authors. Explanations reference factors by cf_id, not by embedding them. This is what unlocks distributed authorship across the strategic layer.

---

Walking toward each other

The structural-premise table above is correct but flat — it reads as “Theses and Observations are the same thing, different vocabulary.” That’s not the full picture. The metapattern they share is the shape. What the table doesn’t carry is the direction each one travels. That direction is the load-bearing piece of Sense 15.

       Observations (top-down, outside-in)
                  │
              Observation ─────────┐
              about the environment │  ← descends from
                                    │    environment toward
                                    │    data-checkable proposition
                                    ▼
                          ┌─────────────────┐
                          │  Understanding  │  ← meeting point
                          │ Findings · Verdicts │     (when they meet)
                          └─────────────────┘
                                    ▲
                                    │  ← ascends from data
                                    │    toward strategic
                                    │    relevance
              Thesis ────────────────┘
              about the data
                  │
            Data (bottom-up, inside-out)

A Thesis is a proposition that ascends from the data. The analyst sees patterns in the signals, codifies the question they suggest, and the proposition rises one tier at a time toward the question “is this strategic?”.

An Observation is a notice that descends from the environment. The executive (or the dean, the CFO, the board) names what the organisation looks like in the world — “we are losing money on generics,” “the OR backlog is shifting,” — and the notice travels down toward the question “is this data-checkable?”.

They walk toward each other. Three things follow.

1. The asymmetry inside the symmetry

The metapattern is shared (proposition + truth-state + anchors → explanation). The polarity is not. A Thesis is born from the data and reaches toward the question of strategic relevance. An Observation is born from the world and reaches toward the question of data confirmation. The structural shape lets them use the same editor, the same validator pattern, the same anchor grammar. The direction tells the system who’s responsible for what — analysts steward Theses, curators steward Observations, neither party can fully discharge the other’s accountability.

This matters for authoring. When you sit down to write a Thesis, the question in front of you is “the data shows X; is X strategic enough to test?”. When you sit down to write an Observation, the question is “X is happening in the world; what evidence convinces stakeholders?”. Same form fields, opposite mental frames.

2. Meeting is optional — and not-meeting is first-class

Most BI tools force every strategic notice to be data-derived. They have no shape for “I see this in the environment and the data doesn’t see it yet — or maybe ever.” jinflow does. An Observation can be fully validated by surveys, citations, and named expert testimony without ever citing a signal. That isn’t a degenerate state; it’s a normal one. The walks can travel their full path without converging.

When they do converge — when an Observation cites a Thesis among its Validation anchors, or when a Thesis surfaces in an Observation’s Used by panel — the encounter is the strategic payoff. Two things become true simultaneously: the executive’s notice is corroborated by the analyst’s evidence, and the analyst’s pattern is lifted to strategic altitude. This is what jinflow exists to make legible.

But the willingness to meet is what matters, not the meeting itself. An Observation whose Validation is purely external is still walking toward the data-checkable case — it just hasn’t arrived, and may never. The system records the walk, not just the destination.

3. Cross-references are the surface of the encounter

The “Used by” panel, the ↗ jump-link, the ⚠ cross-ref warning chip — these are not navigation conveniences. They are the surface where the two walks recognise each other. A Thesis viewing its “Used by” panel and finding “Observation obs_revenue_leakage cites this — validation.anchors” is the moment a strategic notice acknowledges an analytical proposition as part of its case. A curator opening an Observation editor and seeing “this Thesis exists, but is currently not_observed” is the moment a strategic notice discovers it doesn’t have analytical support.

This is why the Phase 1 plumbing landed Used by + ↗ + ⚠ together before the Observations room shipped. They aren’t UX polish; they are the structural feature that makes the diamond’s two directions legible to each other.

What the framing rules out

A few things the walking-toward-each-other framing helps us not build:

• A “Thesis-to-Observation promotion wizard.” Nothing prevents an analyst from authoring an Observation that cites their Thesis, but the system shouldn’t pretend the two artifacts are interchangeable. They aren’t.
• An “evidence quality score” that ranks internal-only Validation above mixed or external-only. The framing makes the not-meeting case first-class; ranking against it is a category error.
• A status state called “machinery-confirmed”. The truth-state enum (suspected / validated / refuted / inconclusive / resolved) is about whether stakeholders are convinced, not about whether the machinery happened to be the convincing party.

The framing is open enough to extend (Sense 19’s Action chain, the Bell’s ring layer, future Observer identity) and tight enough to reject the wrong moves.

---

The three facets of an Observation

The Observations name unfolds into the entity Observation and the two facets it carries — Explanation and Contributing Factor — mirroring how Data unfolds into Signal / Perspective / Thesis / Verdict — but compressed, because Observations is human-authored at every level without machinery doing aggregation work in between.

Tier	Mirrors	Asks	Authored by	Cardinality	Lives in
Observation	Thesis	What’s true about the environment?	One named human (executive, board, dean, CFO)	Rare — 8–20 active per tenant	<afs>/observations/*.yaml
Explanation	Verdict	Why is this Observation as it is?	One named human per Explanation (often the same; sometimes another curator)	1:n with Observation — multiple competing theories allowed	Embedded as explanations[] in the Observation YAML
Contributing Factor	Verdict’s conditions[]	What is one specific cause that contributes?	One named human per factor (SMEs, analysts, the curator)	m:n with Explanations — reusable across Observations	<afs>/contributing_factors/cf_*.yaml — first-class

Observation — the strategic Thesis

A signed strategic notice about the environment the tenant operates in, phrased in the language of the person who pays for the system. Examples:

• “We’re losing money on generic substitutions across all three hospitals.”
• “The OR backlog is shifting toward outpatient procedures faster than staffing reflects.”
• “This institute’s dual-appointment pattern is unusual for the region but appears intentional.”

An Observation is about the world, not about the data. The data can be one of many pieces of evidence the curator presents in Validation, but the Observation doesn’t depend on it. A curator can author a fully-validated Observation whose sole evidence is the quarterly employee survey and a regulatory citation — no signals, no theses, no findings. That’s a normal case, not a degenerate one.

Whether the spark was a hunch or a striking Verdict is process trivia — the schema doesn’t record it. What the schema records is the lifecycle: suspected while Validation is being assembled, validated once enough evidence is in to convince stakeholders, refuted if evidence contradicts, inconclusive if it’s mixed, resolved when the world has moved on.

Validation — the body of evidence

The collection of evidence the curator presents to convince stakeholders that the Observation is real. It is not equivalent to the Understanding band — it is the broader notion of what counts as evidence to a strategic audience.

Anchor kinds split into two families:

• Internal anchors — references to artifacts inside the AFS: signal, perspective, thesis, verdict, finding, smebit, dossier, observation. These carry an id.
• External anchors — references to evidence outside the AFS:
  • external — a document, link, dashboard ({ label, url?, source?, date? })
  • note — free-form prose evidence ({ content, author, date })
  • survey — a structured external data source ({ label, source, date, url? })
  • citation — a published study or report ({ label, author, url?, date? })

A single Validation can mix kinds freely. “The Q3 employer survey shows X (survey); regulatory filing Y mentions it (citation); signal signal_overtime_creep also fires (signal); the clinical SME’s statement in smebit_xyz corroborates (smebit).” The curator chooses what convinces the audience.

Explanation — the strategic Verdict

A theory of why the Observation holds. An Observation can carry zero, one, or many Explanations — they are 1:n with the Observation. Multiple curators may offer competing or complementary theories, each signed separately. Each Explanation has its own state (draft / active / settled), its own author chain, its own list of Contributing Factor references. “The SAP consultant believes A; the clinical lead believes B; the CFO weights them 0.6/0.4.” The honest plural beats a forced choose-one.

An Observation can sit validated with zero Explanations indefinitely — the honest “we see it, we don’t yet know why” state. That’s a first-class outcome.

Contributing Factor — the atomic citation (first-class)

A reusable proposition about one specific cause that contributes to one or more Observations. Lives in its own file at <afs>/contributing_factors/cf_*.yaml, with a global cf_id, its own author, its own lifecycle. Multiple Explanations reference it by cf_id.

Each Factor:

• Makes one short proposition, tri-/n-lingual (“OR staff skip the manual handoff under time pressure”).
• Has anchors — to internal artifacts (signal, verdict, smebit, etc.) or to external evidence (same anchor schema as Validation).
• Optionally curator_judgment: true — no anchors needed, pure prose.
• Carries its own author and signed_at, independent of any Observation or Explanation that cites it.

When an Explanation references a Factor, it can override two things for that Explanation: the role (primary / secondary / modifier / counter, including the counter-factor honesty hook) and the confidence (0–1). The same Factor cited from two different Explanations may carry different roles and confidences in each — its contribution is contextual.

Factors are append-only by default. Supersession works at the Factor level: cf_old → cf_new via superseded_by, preserving history.

---

Where Sense 15 sits in the diamond

                      Observations
                          │
              ┌──────  Sense 15  ──────┐
              │  Observation (entity)  │
              │   carries Explanation  │
              │   and Contributing     │
              │   Factor as facets     │
              └────────────────────────┘
                          │
                          ▼
                  ┌─────────────────┐
       Knowledge ─► Understanding ◄─ Data        ← Sense 14 (Signal,
                  └─────────────────┘                Perspective, Thesis,
                          │                          Verdict)
                          ▼
                      Progress  ← Sense 19 (Suggestion,
                                   Intervention, Scenario,
                                   Simulation, Direction)

Sense 15 owns the Observations name. The Atelier (Sense 29) owns authoring across the Data name (signals, perspectives, theses, verdicts). Subject Matter (Sense 14 sibling) lives inside the Knowledge name alongside the pack’s activatable patterns. The Understanding name (Findings + Verdicts) is the shared currency — all three feeders (Observations, Knowledge, Data) read from and write to it.

Sense 15 surfaces are not the Atelier. The Atelier is the analyst’s workshop; the Observations surface is the executive’s bridge. Distinct audience, distinct affordances, distinct vocabulary. Same engine underneath.

---

Two lifecycles

An Observation carries two independent state machines.

Editorial lifecycle — Is the curator maintaining this?

draft ─► active ─► dormant ─► resolved ─► superseded
                       ▲                       │
                       └───────────────────────┘
                       (reactivation if the pattern recurs)

• draft — being authored; not visible on the dashboard.
• active — signed, on the executive dashboard, currently being maintained.
• dormant — invisible by default but preserved with full history. Reactivates automatically if the pattern recurs (Bell signal).
• resolved — the curator explicitly closed it; the underlying issue was addressed.
• superseded — replaced by a narrower or broader Observation. superseded_by points forward; supersedes points back.

Truth lifecycle — What does the data say?

suspected ─┬─► validated  ─┐
           ├─► refuted     │
           ├─► inconclusive├─► resolved
           │                │
           └────────────────┘
                  (when the world has moved on)

• suspected — notice authored, validation not yet run. First-class state. C-level walks in with hunches; jinflow gives those hunches a typed home and an explicit obligation to validate.
• validated — Findings + Verdicts corroborate. Move to Explanation.
• refuted — Findings + Verdicts contradict. The Explanation now explains why the notice was wrong — equally valuable.
• inconclusive — machinery ran but evidence is mixed or magnitude is too small to decide. First-class state. Most BI tools pretend everything is yes/no; jinflow says sometimes the world doesn’t answer cleanly.
• resolved — action taken; the question is no longer live.

The two lifecycles do not interact at the model level. An Observation can be active (editorial) and inconclusive (truth) simultaneously: the curator is maintaining it; the data hasn’t decided yet. They render as two separate badges in the surface.

inconclusive (strategic) ≠ insufficient (operational)

A subtle distinction worth carrying verbatim:

	insufficient (Thesis)	inconclusive (Observation)
Layer	Data (Sense 14)	Observations (Sense 15)
What broke	The evidence pipeline	The strategic question itself
Honest translation	”We couldn’t run the test."	"We ran the test. The world didn’t answer.”
Remedy	Build more signals; fix data	Sharpen the notice; add Factors; or accept ambiguity

insufficient can feed into inconclusive, but they’re not synonyms.

---

Substrate: YAML in AFS

Decision: Observations live as YAML files in the tenant AFS.

<live_root>/<pack>/<tenant>/afs/
  observations/
    obs_2026_q1_material_leakage.yaml
    obs_or_backlog_outpatient_shift.yaml
    ...

Why YAML in AFS, not notes

The April doc leaned notes-only because notes already carried author, timestamp, history, threading, replies. Today:

• The Atelier writer pattern (atomic tmp+rename → git add → git commit with semantic prefix) carries everything notes did, plus git versioning, branchability for scenarios, divergence badges, Atelier-style validators, the writer integration tests, and the cross-reference machinery (atelier_xref.ts).
• Observations are scenario-relevant. A curator may want to author an Observation on a branch to explore a strategic notice without committing to main. YAML in AFS gets that for free; notes don’t.
• Threads belong to Bell. The conversation around an Observation (replies, comments, attached findings) is naturally a Bell ring anchored to the Observation id. Bell already does threading. We don’t need to reinvent it inside the Observation record.

Substrate decision: YAML for the spine, Bell for the conversation.

Why not the Atelier directory

Although Observations are YAML-in-AFS like the B-tier artifacts the Atelier edits (smebits, signals, theses, verdicts, dossiers, perspectives), they sit in a different room:

• Different audience: executives, not analysts.
• Different vocabulary: notice/validate/explain, not balance/condition/evidence.
• Different cadence: rare and high-stakes, not iterative.

The Observations surface is a peer to the Atelier, not a tab inside it.

---

YAML schema sketch

Observation file

observations/obs_2026_q1_material_leakage.yaml

observation_id: obs_2026_q1_material_leakage
kind: observation               # constant — reserves polymorphism if needed
version: 1.0.0

editorial_state: active         # draft | active | dormant | resolved | superseded
truth_state: validated          # suspected | validated | refuted | inconclusive | resolved

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

scope:
  tenant_id: hospital_zeta
  # cross_tenant: [vai, inspire]   # optional, Phase 2

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:                          # markdown body, one per locale
  en: |
    Over the past 12 months we observe a persistent gap between OR
    material usage and corresponding billing events. Exposure to
    date: CHF 340K. Concentrated in wards 3, 5, 7. Stable, not growing.
    This is a structural leak, not a recent regression.
  de: |
    (...)
  fr: |
    (...)

# The body of evidence presented to convince stakeholders. Mix
# internal (signal/thesis/verdict/smebit/...) and external (survey/
# citation/note/external) freely.
validation:
  anchors:
    # Internal — carries `id` referencing an AFS artifact.
    - { kind: signal,  id: signal_revenue_leakage, role: primary }
    - { kind: thesis,  id: thesis_revenue_leakage_unbilled }
    - { kind: verdict, id: verdict_billing_workflow_gap, role: supporting }
    # External — no internal id; carries label + source.
    - kind: survey
      label: "Q3 OR Staff Survey — handoff fatigue"
      source: "HR Department"
      date: "2026-03-15"
      url: "https://internal.example.com/surveys/2026q3-or.pdf"
      role: supporting
    - kind: citation
      label: "Lewis & Roth (2024) — manual-handoff failure modes"
      author: "Lewis JT, Roth K"
      url: "https://doi.org/10.xxxx/yyyyy"
      role: context
    - kind: note
      content: "Three department heads independently raised this in the leadership meeting on 2026-03-22."
      author: "the owner Käfer"
      date: "2026-03-22"
      role: supporting
  last_checked_at: 2026-04-05T10:30:00Z

# Zero, one, or many Explanations. Each is one curator's theory of why,
# composed of references to Contributing Factor files. An empty list is
# meaningful — "validated but no theory yet".
explanations:
  - explanation_id: exp_workflow_gap_theory
    state: active                 # draft | active | settled
    author:
      name: Dr. Jane Doe
      role: Clinical Lead
      signed_at: 2026-04-05T11:15:00Z
    last_updated: 2026-04-12T16:00:00Z
    factor_refs:
      # role + confidence are *contextual to this Explanation* —
      # the same cf may carry different role/confidence in a peer
      # Explanation.
      - cf_id: cf_or_paper_handoff_skip
        role: primary               # primary | secondary | modifier | counter
        confidence: 0.73
      - cf_id: cf_catalogue_staleness
        role: secondary
        confidence: 0.55
      - cf_id: cf_or_volume_increase
        role: counter
        confidence: 0.80            # strong counter — the underlying rate is worse than it looks

  # A competing theory by a different curator, e.g. the SAP consultant
  # who weights catalogue staleness as the primary driver.
  - explanation_id: exp_data_quality_first
    state: active
    author:
      name: Alex Weber
      role: SAP Consultant
      signed_at: 2026-04-10T09:30:00Z
    factor_refs:
      - { cf_id: cf_catalogue_staleness,  role: primary,   confidence: 0.70 }
      - { cf_id: cf_or_paper_handoff_skip, role: secondary, confidence: 0.40 }

# Append-only lifecycle history.
editorial_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" }
truth_history:
  - { state: suspected, at: 2026-04-05T09:00:00Z, by: mig }
  - { state: validated, at: 2026-04-05T10:25:00Z, by: mig,
      note: "survey + signal + thesis all aligned; CFO accepts" }

supersedes:    null              # observation_id this replaces
superseded_by: null              # observation_id that replaces this

tags: [revenue, billing, OR]

Contributing Factor file

Lives in its own file. Multiple Observations can reference it.

contributing_factors/cf_or_paper_handoff_skip.yaml

cf_id: cf_or_paper_handoff_skip
version: 1.0.0

statement:
  en: "OR staff skip the manual billing handoff under time pressure."
  de: "(...)"
  fr: "(...)"

author:
  name: Dr. Jane Doe
  role: Clinical Lead
  signed_at: 2026-04-05T11:15:00Z

# What backs this factor. Same anchor schema as Validation —
# can be internal artifacts or external evidence.
anchors:
  - { kind: smebit, id: smebit_or_paper_tracking }
  - { kind: signal, id: signal_missing_billing_handoff }
  - kind: note
    content: "Observed during three OR-shadowing sessions in March 2026."
    author: "Dr. Jane Doe"
    date: "2026-03-30"

# Optional — declare this is pure curator judgment (no anchors needed).
# curator_judgment: true

# Optional — a factor can become superseded by a sharper version.
supersedes: null
superseded_by: null

# Lifecycle for Factor itself (separate from any Observation's
# truth state). draft → active → retired.
status: active

Schema notes

• Tri-/n-lingual fields follow the tenant-locale-aware pattern already used by the Atelier — config-driven, not hardcoded.
• validation.anchors[] accepts internal artifacts (carry id) and external evidence (external/note/survey/citation — carry label/url/source/date/content instead).
• explanations[] is a list of theories. Each one stands on its own with its own state, author, and factor references.
• Contributing Factors live in <afs>/contributing_factors/cf_*.yaml. An Explanation cites them by cf_id with contextual role + confidence — the same Factor can carry different role/confidence in different Explanations.
• editorial_history and truth_history are append-only logs.
• The origin field is gone — Observations are always about the environment regardless of what sparked them.
• The cross-ref walker (atelier_xref.ts) already understands the new anchor shapes. Editors viewing a Signal/Thesis/etc. see which Observations and which Contributing Factors cite them.

---

Edges into the rest of the system

Observation
  │
  ├── validation.anchors ──► Signal / Thesis / Verdict / Finding
  │   (auto-rendered "show me" panel; reads Understanding rows)
  │
  ├── explanation.contributing_factors[].anchors ──► same set + Subject Matter
  │   (curator-curated; cites Understanding + Expertise)
  │
  ├── supersedes / superseded_by ──► another Observation
  │
  └── (later, Sense 19) ──► Suggestion ─► Intervention ─► Scenario ─► Simulation

atelier_xref.ts extends with one new artifact kind. Every existing B-tier editor’s “Used by” panel gains a sixth section (“these Observations cite this signal/thesis/verdict/smebit”) for free once the walker scans observations/*.yaml.

---

Surface — the Observations room

Sense 15 needs a surface, peer to the Atelier and distinct from it. The sidebar calls the room Observations in V2; the i18n slug (nav.strategy, with /observations as its first entry). The room takes the same name — no new brand. The Observations room reads; the Atelier authors the machinery beneath it; the Bell tracks the conversation around both.

Routes (Phase 1)

/<tenant>/observations              ← dashboard (card grid)
/<tenant>/observations/[id]         ← detail view (read-mostly)
/<tenant>/observations/[id]/edit    ← editor (Atelier-style)
/<tenant>/observations/new          ← observation-id wizard

Dashboard shape

The C-level entry point. 8–20 active Observations, rendered as cards:

┌──────────────────────────────────────────────────────────┐
│ Material usage not matched by billing in OR wards        │
│ ● validated   ● active                                   │
│ Signed by the owner Käfer · Lead Analyst · 2026-04-05          │
│ Past 12 months · CHF 340K exposure · 247 findings        │
│                                                          │
│ "Over the past 12 months we observe a persistent gap…"   │
└──────────────────────────────────────────────────────────┘

Two badges (editorial + truth). One-line title. Two-line summary preview. Click → detail.

Detail shape

The CEO opens the detail page and sees:

1. The notice — title, summary, signed-by, time window.
2. Show me (Validation) — auto-rendered from validation.anchors: the cited findings, a small chart of the underlying signal, the thesis status, the verdict status. Empirical, not debatable.
3. Why (Explanation) — Contributing Factors rendered as signed cards in role order (primary → secondary → modifier → counter). Each Factor shows author, confidence bar, anchored evidence.
4. History — editorial + truth lifecycle, supersession chain.

Three clicks from what? to why?. Zero analyst vocabulary required to read.

Editor shape

Atelier-style: server-loaded YAML, client-side form, validator, divergence badge, save → git commit. Reuses XrefStatus, UsedByPanel, the tenant-locale tabs, the editor scaffolding.

---

Accountability chain

Artifact	Authored by	Signed?
Signal	Analyst	Collective (YAML in git)
Perspective	Analyst	Collective
Thesis	Business analyst	Collective
Verdict	Rule engine	No — computed
Finding	Machine	No — atomic event
Subject Matter Statement	Domain expert	Yes — provider
Subject Matter Check	Domain expert	Yes — provider
Dossier	Curator	Yes — curator
Observation	Curator (one named human)	Yes — author, non-delegable
Contributing Factor	Often a different human per factor	Yes — author per Factor

Observations and Contributing Factors join Statements, Checks, and Dossiers as the artifacts that carry an actual person’s name. Together they form the human spine of jinflow.

---

Observation vs Subject Matter Statement

Both are signed prose; both express human knowledge; both look similar in YAML. The distinction is what they’re about:

	Subject Matter Statement	Observation
About	A fact of the world (“OR staff skip handoffs under time pressure”)	A notice about the business (“We’re losing money on generic substitutions”)
Role	Knowledge — informs	Observations — top-down
Cardinality	Many (institutional knowledge accumulates)	Rare (8–20 active)
Lifecycle	active / dormant (no truth state — it’s expertise, not a hypothesis)	Editorial + truth
Connects to	Anchored to entities, signals, theses; informs Understanding	Anchored to findings, verdicts; tested by Understanding
Surface	Atelier (analyst’s workshop)	Observations room (executive bridge)
Replaces	(nothing — pure knowledge)	The old /interpretations route

A Subject Matter Statement might anchor a Contributing Factor — “OR staff skip handoffs” (Statement) is the cause asserted by Factor ”… and that’s why billing gaps fire” (Factor in an Observation’s Explanation).

The Atelier creates and edits Statements. The Observations room reads them as one kind of anchor among many.

---

Phase 1 — what we ship first

Three sub-phases, each independently useful, each landing in its own session.

Phase 1a — Observation foundation (SHIPPED 2026-05-18)

• Observation schema + validator + 16 unit tests
• listObservations + loadObservation in atelier.ts
• saveObservation writer (via Strategy commit prefix)
• /observations list page with editorial + truth state facets
• /observations/new wizard
• Cross-ref walker extension for observations/
• UsedByPanel integration (Observations show first)

Phase 1b — Observation editor + detail + schema evolution

• Schema evolution to match today’s decisions (this session, 2026-05-18):
  • Widen validation.anchors[] to internal + external kinds
  • Drop origin field
  • explanations[] array — multiple competing theories per Observation
  • Contributing Factors become first-class files at <afs>/contributing_factors/cf_*.yaml; Explanations reference by cf_id with contextual role + confidence
• Routes: /<tenant>/observations/[id] (detail, read-mostly) and /<tenant>/observations/[id]/edit (editor)
• Editor surface: Atelier-style with anchor pickers, XrefStatus on every reference, UsedByPanel, divergence badge, two-lifecycle state badges
• Anchor picker widens to handle both internal artifacts and external evidence (URL/label/source/date/note)

Phase 1c — Contributing Factor surface

• /<tenant>/contributing-factors — list/dashboard, filter by status
• /<tenant>/contributing-factors/new — cf-id wizard
• /<tenant>/contributing-factors/[id] — detail
• /<tenant>/contributing-factors/[id]/edit — editor
• Cross-ref walker: walking back from a CF shows all Explanations that cite it (across all Observations)
• Observation editor’s factor-picker resolves against the CF catalog; missing references render as ⚠ (cross-ref validation pattern from yesterday)

---

Out of scope for Phase 1

• Auto-rendered Validation panel. Phase 1 lists the anchors with chips. Phase 2 renders a small chart + finding table beneath each internal anchor, an iframe / preview for external ones.
• Auto-proposal engine (“would you like to promote this finding to an Observation?”).
• Bell threading. Curators discuss in person and via tickets in Phase 1; rings on Observations come in Phase 2.
• Cross-tenant scope. Phase 2.
• Visibility levels (internal / executive / board). Phase 2.
• Localization automation. Curators write all locales by hand in Phase 1, same as smebit / thesis. Auto-translate is a separate question for every B-tier artifact.
• Sense 19 bridge (Suggestion authoring from Contributing Factors). Suggestions belong to the Action band and ship under Sense 19, not here.

---

Decisions still to land before Phase 1

These need a sentence-each answer; they’re small but blocking.

1. Name of the surface. The sidebar section is already called Observations (nav.strategy legacy i18n slug, with /observations as its first entry). Adopt Observations as the V2 room name — same word as the diamond’s band, same word as the sidebar section, same word as the route’s conceptual parent. No new brand required.

2. Editorial vs truth interaction. Can a draft Observation be validated? Recommend: no — validation requires editorial_state ∈ {active, dormant}. Drafts are not real until signed.

3. resolved semantics — editorial vs truth. Both lifecycles have a resolved state. Same word, two layers. Recommend: keep both, render with disambiguating labels (“Curator resolved” vs “World resolved”). The honesty cost of merging them is higher than the cost of carrying both.

4. Findings as anchors. Anchors of kind: finding carry the finding_id string the engine already generates (string-typed PK of signal_findings__*, confirmed at signal_contract.v1.json:9). No composite key invented.

5. kind: observation constant — keep or drop? Reserves room for sibling kinds inside the same directory (Hypotheses? Conjectures? Wagers?). Recommend: keep. Cheap insurance.

6. The walking-toward-each-other framing. Theses and Observations share the metapattern (proposition + truth state + anchors → explanation) but diverge sharply in what counts as evidence. They walk toward each other: Data ascends from rows, Observations descends from the environment. When they meet at Understanding — an Observation cites a Thesis among its anchors; a Thesis surfaces in an Observation’s Used by panel — the encounter is the strategic payoff. They don’t have to meet; an Observation can be fully validated by surveys + expert testimony alone. Recorded here so the schema and editor surface honour both the meeting case and the never-meeting case as first-class.

---

How this manifests in jinflow

The Observations name sits above the Sense 14 chain: an Observation is the entity — a signed notice by a named person, with state — and carries Explanation and Contributing Factor as facets. Contributing Factors cite specific Findings or Verdicts from Understanding, grounding the narrative in the truth-bearing band. Both Observations and Contributing Factors have their own JinDesk surfaces today, with create + edit + detail routes — the Atelier-style write path lands authored YAML straight into the tenant AFS.

• In the app: Observations (list, new, per-observation detail) · Contributing Factors (list, new, per-factor detail)
• Writes to: tenant AFS at observations/*.yaml and contributing_factors/*.yaml, via the Scribe boundary (Sense 38)

Status: shipped (Phase 1 — the write surfaces and contracts are live). The signing layer (Sense 25 Pass attribution per author) is wired in; the deeper validation chain (auto-linking Observations to confirmed Theses’ Findings) is forming.

---

What this doc does not try to do

• It doesn’t redefine the diamond. That’s the_jinflow.md.
• It doesn’t specify the Atelier’s behaviour. That’s settled.
• It doesn’t say anything about Sense 19 except where the handoff occurs. Sense 19 has its own doc.
• It doesn’t describe the auto-proposal engine. That’s a separate follow-on once Phase 1 is on real Observations and we know what patterns we’d want the system to surface.

---

The one-sentence summary

After Sense 14 gave the machinery its vocabulary and the Atelier gave the analysts their workshop, Sense 15 gives the executives their voice — Observation for the notice, Validation as the act of checking it against Understanding, Explanation for the theory, built from signed Contributing Factors — all of it living as YAML in the AFS, branchable for scenarios, peer to the Atelier but a separate room of its own.

---

Numerical neighbors: ← Sense 14.2: Typed Signals — Dimensions, Units, and Standards · Sense 15: Observation and Explanation →