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 SMEbits — atomic, attributed, versioned pieces of expert knowledge.

The problem

Today, creating an SMEbit 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 analytical pyramid — signals, theses, verdicts — is built by engineers and analysts. But the knowledge that makes the pyramid 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 (Explorer)

A guided flow inside the Explorer. 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 SMEbit. 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 (Explorer 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 SMEbit draft (observation only, 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 SMEbits. 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 SMEbit 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 an SMEbit 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 (Level 1) or remain an observation (Level 0).
4. Commit. The reviewed SMEbit is saved to the AFS as a YAML file. It is now part of the analytical framework.
5. Build. jinflow make compiles the SMEbit into the KLS. Level 1 SMEbits produce verdicts (confirmed/violated/no_data). Level 0 SMEbits appear in the registry.
6. Surface. The Explorer shows SMEbits alongside the findings and theses they relate 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
SMEbit YAML format	Shipped. See YAML reference.
Validator (smebitcheck.py)	Shipped. Validates structure, references, scope.
Compiler (smebitcompile.py)	Shipped. YAML to dbt SQL.
SMEbit registry + verdicts in KLS	Shipped. Level 0 in registry, Level 1 verdicts.
SMEbit display in Explorer	Shipped. List page, detail page, anchors to signals/theses.
BitBundles (narrative groupings)	Shipped. Curate SMEbits into stories. See YAML reference.
Interview mode in Explorer	Planned. Guided capture flow.
Quick capture button	Planned. One-click from entity/finding pages.
Draft-review-commit workflow	Planned. In-Explorer editing with AFS write-back.
Voice capture	Future. AI transcription to candidate SMEbits.

The engine treats SMEbits as first-class instruments — they have 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.”