Quote the match
{ "matched_text": "[clinical phrase]", "filename": "[source name]" }Convenient debugging; duplicated content.
Designing explainability · Entry 017
The quiet copy.
Our classifier needed to explain itself. A design review showed how matched text, snippets, and filenames could turn that explanation into an unnecessary second store of clinical content.
Chapter 01
An explanation can become a data store.
The protected payload was not the only place sensitive text could survive. Evidence strings, debug context, exceptions, and audit events each have their own access and retention lifecycle.
Reference the rule
{ "rule_id": "physician_order.header", "source": "text", "weight": 3 }Traceable reasoning without repeating the document.
Chapter 02
Reference the governed definition.
The event points to a versioned rule registry. Reviewers can understand which rule contributed while the clinical source stays inside the system designed to protect it.
Preserve the reason.
Leave the patient’s words at the source.
Leave the patient’s words at the source.
Chapter 03
Make the boundary executable.
A code review convention can drift. The schema and tests reject unknown evidence shapes, free-form snippets, and synthetic canary phrases in serialized audit events.
| Assertion | Protects | Does not prove |
|---|---|---|
| Rule ID exists | Evidence resolves to reviewed logic | The rule itself is clinically valid |
| No free-form content | The contract cannot quote a document | No other log can leak data |
| Canary absent | Known synthetic text is not serialized | Whole-system HIPAA compliance |
Sources
Logging is a governed lifecycle.
Primary guidance supports treating logs as managed records, not disposable exhaust.
Visual edition
The quiet copy.
A narrated walkthrough of the evidence contract, rule registry, and hygiene test that keep explanation from becoming a shadow clinical record.