Skill Tracer
Skills › Scientific Agent Skills › clinical-decision-support › decision_logic_traceability.md

decision_logic_traceability.md

146 lines · skills/clinical-decision-support/references/decision_logic_traceability.md at 5f2bc03

Open on GitHub

Most marks come from matching words in the file, so treat them as pointers.

1# Decision-Logic Traceability
2

Decision-Logic Traceability

Raw lines 1 to 2
3## Scope
4
5“Decision logic” here means research and governance logic only:
6
7- evidence inclusion/exclusion;
8- data-quality gates;
9- validation acceptance criteria;
10- release holds;
11- documentation completeness;
12- change-control approval;
13- human-review checkpoints.
15Do not encode diagnostic, treatment, dosing, triage, alarm, urgency, bedside, or patient-facing logic.

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.

Raw lines 3 to 16
17## Matrix Purpose
19A traceability matrix links each rule to:
21- its source and rationale;
22- input/precondition;
23- deterministic statement;
24- bounded output kind;
25- verification tests;
26- owner and reviewer;
27- version and status;
28- known limitations and change history.
30The matrix documents logic. It does not execute arbitrary expressions.

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.

Raw lines 17 to 31
32## Allowed Node Types
34- `input_check`
35- `data_quality_gate`
36- `evidence_rule`
37- `validation_gate`
38- `documentation_gate`
39- `human_review`
40- `release_gate`
41- `monitoring_gate`
43Allowed output kinds:
45- `include_evidence`
46- `exclude_evidence`
47- `flag_for_review`
48- `validation_status`
49- `documentation_status`
50- `release_hold`
51- `monitoring_status`
53There is deliberately no generic “action” node.

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.

Raw lines 32 to 54
55## Required Fields

Required Fields

Raw lines 55 to 56
57### Matrix Metadata
59- logic ID and title;
60- version/status/owner;
61- research-only intended use;
62- prohibited uses;
63- data level;
64- source ledger;
65- human-review requirement;
66- change summary;
67- monitoring and retirement criteria.

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.
Raw lines 57 to 68
69### Per Node
71- unique node ID;
72- type;
73- precondition/input;
74- logic statement in plain language;
75- output kind;
76- output value;
77- source IDs;
78- rationale;
79- validation tests;
80- owner;
81- reviewer role;
82- status.

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.
Raw lines 69 to 83
84## Rule-Writing Guidance
86Write rules so an independent reviewer can reproduce the result without hidden knowledge.
88Good:
90> If an evidence record lacks a stable citation and retrieval date, set output kind `flag_for_review` with value `missing_source_provenance`.
92> If external validation is absent, set `release_hold` to `true` for claims of transportability.
94Unsafe and prohibited:
96> If a person's score is high, trigger an urgent alert.
98> If a biomarker is positive, recommend a therapy.

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.
Raw lines 84 to 99
100## Validation Tests
102For each node include:
104- positive case;
105- negative case;
106- boundary case;
107- missing/invalid input;
108- source/version regression;
109- expected output;
110- reviewer and date.
112For the matrix as a whole include:
114- unreachable or orphan nodes;
115- conflicting outputs;
116- cycles;
117- missing sources;
118- stale versions;
119- bypass paths around human review;
120- rollback and retirement behavior.
122The 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. Invalid matrices produce diagnostics without CSV export; `--strict` also withholds export when review warnings remain.

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. Invalid matrices produce diagnostics without CSV export; --strict also withholds export when review warnings remain.

Raw lines 100 to 123
124## Change Control
126For any change:
1281. state the reason;
1292. link new evidence or requirement;
1303. identify affected nodes and downstream artifacts;
1314. update tests;
1325. independently validate;
1336. record approval;
1347. define rollout/rollback when applicable;
1358. retain the previous version;
1369. update monitoring;
13710. retire superseded logic explicitly.

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.
Raw lines 124 to 138
139## Script
141```bash
142python3 scripts/decision_logic_traceability.py \
143 assets/decision_logic_traceability_template.json
144```
146The output is a documentation matrix, not executable clinical logic.

Script

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

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

Raw lines 139 to 146
Runs code python3 scripts/decision_logic_traceability.py :142