Decision-Logic Traceability

Scope

“Decision logic” here means research and governance logic only:

• evidence inclusion/exclusion;
• data-quality gates;
• validation acceptance criteria;
• release holds;
• documentation completeness;
• change-control approval;
• human-review checkpoints.

Do not encode diagnostic, treatment, dosing, triage, alarm, urgency, bedside, or patient-facing logic.

Matrix Purpose

A traceability matrix links each rule to:

• its source and rationale;
• input/precondition;
• deterministic statement;
• bounded output kind;
• verification tests;
• owner and reviewer;
• version and status;
• known limitations and change history.

The matrix documents logic. It does not execute arbitrary expressions.

Allowed Node Types

• input_check
• data_quality_gate
• evidence_rule
• validation_gate
• documentation_gate
• human_review
• release_gate
• monitoring_gate

Allowed output kinds:

• include_evidence
• exclude_evidence
• flag_for_review
• validation_status
• documentation_status
• release_hold
• monitoring_status

There is deliberately no generic “action” node.

Required Fields

Matrix Metadata

• logic ID and title;
• version/status/owner;
• research-only intended use;
• prohibited uses;
• data level;
• source ledger;
• human-review requirement;
• change summary;
• monitoring and retirement criteria.

Per Node

• unique node ID;
• type;
• precondition/input;
• logic statement in plain language;
• output kind;
• output value;
• source IDs;
• rationale;
• validation tests;
• owner;
• reviewer role;
• status.

Rule-Writing Guidance

Write rules so an independent reviewer can reproduce the result without hidden knowledge.

Good:

If an evidence record lacks a stable citation and retrieval date, set output kind flag_for_review with value missing_source_provenance.

If external validation is absent, set release_hold to true for claims of transportability.

Unsafe and prohibited:

If a person's score is high, trigger an urgent alert.

If a biomarker is positive, recommend a therapy.

Validation Tests

For each node include:

• positive case;
• negative case;
• boundary case;
• missing/invalid input;
• source/version regression;
• expected output;
• reviewer and date.

For the matrix as a whole include:

• unreachable or orphan nodes;
• conflicting outputs;
• cycles;
• missing sources;
• stale versions;
• bypass paths around human review;
• rollback and retirement behavior.

The bundled helper validates identifiers, allowed node/output types, citations, and required review fields, then emits CSV. It does not parse or execute the logic statement.

Change Control

For any change:

1. state the reason;
2. link new evidence or requirement;
3. identify affected nodes and downstream artifacts;
4. update tests;
5. independently validate;
6. record approval;
7. define rollout/rollback when applicable;
8. retain the previous version;
9. update monitoring;
10. retire superseded logic explicitly.

Script

python3 scripts/decision_logic_traceability.py \
  assets/decision_logic_traceability_template.json

The output is a documentation matrix, not executable clinical logic.