Expert Knowledge Capture

The Subject Matter Expert — Fachexperte — is the person who knows things the data cannot show.

Marie-Therese knows her old vines produce less by design. The customs clerk knows Shanghai holds electronics for 48 hours. The warehouse manager knows Sunday driving bans cause weekly checkpoint gaps. The head nurse knows that ward 3B codes procedures differently because their legacy terminal only has 6 character fields.

Their knowledge is the difference between a false alarm and an insight. jinflow captures it as Subject Matter — atomic, attributed, versioned pieces of expert knowledge.

The problem

Today, capturing a piece of Subject Matter requires writing YAML. The SME does not write YAML. They talk, they point at screens, they say “that’s not a problem, that’s how it works here.” There is a gap between the person who knows and the system that needs to know.

The diamond — signals, theses, verdicts — is built by engineers and analysts. But the knowledge that makes the diamond trustworthy comes from people who will never open a text editor. If capturing their knowledge requires a developer as intermediary, that knowledge leaks away at every handoff.

The vision: guided capture

Three capture modes, from simplest to richest.

1. Interview mode (JinDesk)

A guided flow inside JinDesk. The analyst shows a finding to the SME. The SME says “I know why this is.” The system asks structured questions:

• What do you know? (the content)
• Why is it this way? (the reason)
• Does this apply everywhere or just here? (the scope)
• Should the system check this automatically? (the level)

The answers become a draft entry. The analyst reviews, refines the scope and category, and commits it to the AFS. On the next build, the knowledge is compiled into the KLS and visible to everyone.

2. Quick capture (JinDesk sidebar)

An “I know something about this” button on entity detail pages, finding cards, and thesis evaluations. One click opens a minimal form: subject, content, why. The scope is pre-filled from context — current tenant, current entity, current time range.

This creates a Level 0 Statement — a Subject Matter draft with no executable check. The barrier to entry is one sentence and one click.

3. Voice capture (future)

Record a conversation with the SME. AI transcribes and structures it into candidate Subject Matter entries. The analyst reviews, edits, and commits. The SME never touches a keyboard.

This is the hardest mode to build and the easiest mode to use. It is not yet implemented.

The capture flow

Every entry carries attribution: who said it, when, in what role. The provenance chain is unbroken from person to production.

The lifecycle

A captured piece of knowledge moves through clear stages:

1. Speak. The SME shares what they know, in their own words, in their own language.
2. Draft. The system structures it into a Subject Matter entry with content, scope, and category.
3. Review. The analyst checks the draft — refines wording, sets the right scope, decides if it should have an executable check (a Level 1 Check) or remain a Level 0 Statement.
4. Commit. The reviewed entry is saved to the AFS as a YAML file. It is now part of the analytical framework.
5. Build. jinflow make compiles the Subject Matter into the KLS. Checks produce verdicts (confirmed/violated/no_data). Statements appear in the registry.
6. Surface. JinDesk shows Subject Matter alongside the findings and theses it relates to, via anchors.

The SME sees their contribution reflected in the system. The analyst gets institutional knowledge formalized. The viewer sees findings annotated with context that no algorithm could derive.

What exists today

The foundation is built. What is missing is the capture UI.

Layer	Status
Subject Matter YAML format	Shipped. See YAML reference.
Validator (smebitcheck.py)	Shipped. Validates structure, references, scope.
Compiler (smebitcompile.py)	Shipped. YAML to dbt SQL.
Subject Matter registry + verdicts in KLS	Shipped. Statements in the registry, Checks as verdicts.
Subject Matter display in JinDesk	Shipped. List page, detail page, anchors to signals/theses.
Dossiers (narrative groupings)	Shipped. Curate Subject Matter into stories. See YAML reference.
Interview mode in JinDesk	Planned. Guided capture flow.
Quick capture button	Planned. One-click from entity/finding pages.
Draft-review-commit workflow	Planned. In-JinDesk editing with AFS write-back.
Voice capture	Future. AI transcription to candidate entries.

The engine treats Subject Matter as a first-class instrument — it has the same compile-validate-build lifecycle as signals and theses. The missing piece is the front door for the people who hold the knowledge.

The principle

The difference between data and knowledge is the why. The SME provides the why. jinflow’s job is to make contributing that knowledge as easy as having a conversation.

A signal can tell you that ward 3B has 40% fewer coded procedures than ward 3A. A thesis can tell you this pattern is consistent and statistically significant. A verdict can tell you the root cause category is process_failure. But only the head nurse can tell you why — and that why changes what you do about it.

The SME tooling exists to close this loop. Not by making experts into engineers, but by meeting them where they are: in front of the screen, pointing at a number, saying “let me tell you about that.”