Skip to content
PoktaCareDocs

Clinical notes and completeness

This page defines the RheumAI boundary. Current intake, completeness, review, and submission behavior lives in the BiobadamexAI workflow.

The problem

Section titled “The problem”

A note can be well written and still omit a required data point. It can also contain a correct fact that software fails to structure. The system must separate three questions:

  1. What does the note say?
  2. What does the clinical workflow or registry require?
  3. What should the clinician ask or correct before approval?

Current RheumAI capability

Section titled “Current RheumAI capability”

RheumAI can:

  • receive clinical text and files in chat;
  • parse PDF, spreadsheet, CSV, JSON, Markdown, and text files;
  • use vision for some PDFs and images when configured;
  • classify clinical question types and detect some alert terms;
  • retrieve evidence and generate clinical interpretation;
  • ask for missing context through persona and prompt instructions;
  • review response quality with ORVS;
  • process one de-identified note through a stateless study route.

These capabilities can help reveal gaps, but their main output today is narrative text.

What RheumAI does not expose as a contract

Section titled “What RheumAI does not expose as a contract”

The repository does not yet return a structured payload containing:

  • every BIOBADAMEX-required field;
  • the extracted candidate value;
  • the source text span;
  • present, missing, unknown, or not_applicable state;
  • the clinical rule that makes the field applicable;
  • a suggested question for the clinician;
  • clinician approval or rejection.

The study route returns content, provider, model, tools, tokens, latency, and fallback status. It does not return a note-completeness matrix. It also has no deterministic de-identification check, note-specific length limit, final ORVS pass, ethical review, or clinician approval. The caller must satisfy those duties before and after the route.

Section titled “Recommended integration design”

The institutional flow should keep responsibilities separate:

Stage Owner Output
Intake BiobadamexAI Controlled note and internal identifier
Extraction Registry structured service Candidate fields with provenance
Completeness Diagnosis-specific BIOBADAMEX rules Present, missing, unknown, or not-applicable fields
Clinical explanation RheumAI Prioritized gaps and useful clinician questions
Response review ORVS and deterministic controls Accuracy, safety, citation, and coverage flags
Human review Authorized clinician Correction and explicit approval
Submission Controlled registry service Approved data only, with read-back

Central rule

Section titled “Central rule”

RheumAI should detect and ask, not invent. If the note lacks a fact, the integration preserves missing or unknown status according to the clinical rule. Model inference never becomes registry data automatically.

Completeness flow

Section titled “Completeness flow”
  1. The extractor identifies candidate values and preserves supporting text.
  2. The rule engine selects fields applicable to the diagnosis.
  3. The system computes completeness as presence across applicable fields. Accuracy and completeness remain separate metrics.
  4. RheumAI turns gaps into clear, prioritized questions.
  5. ORVS reviews the RheumAI response, not the chart.
  6. The clinician confirms, corrects, or marks data unavailable.
  7. Only the approved version can reach the registry service.

Safeguards

Section titled “Safeguards”
  • Use synthetic or de-identified notes outside the authorized clinical environment.
  • Remember that normal chat can persist messages and files. Long PDFs that resemble articles can also enter the local knowledge directory under current rules.
  • Never place real notes in repositories, docs, logs, or fixtures.
  • Preserve field-level provenance.
  • Do not treat valid 0, false, or dates as missing through generic truthiness checks.
  • Keep missing, unknown, and not applicable distinct where clinical rules require it.
  • Do not let ORVS or narrative output bypass clinician review.
  • Record the model and rules version that created each draft.

Readiness criteria

Section titled “Readiness criteria”

Do not call the integration ready until it has:

  • a versioned input/output contract;
  • diagnosis-specific completeness rules under clinical review;
  • synthetic tests for present and missing fields;
  • clinical review of suggested questions;
  • an audit that the route does not unexpectedly write or log PHI;
  • service-to-service authentication;
  • a fallback that preserves the draft without submission when RheumAI fails.

Code evidence

Section titled “Code evidence”