# Source Document — Adapting WHO HIV DAK L2 Artifacts to Ethiopia: Authoring a Contextualized Decision-Support Table and Indicator

**For:** workshop session — adopting and adapting additional L2 artifacts to the Ethiopian context, with a hands-on focus on authoring contextualized decision-support and indicator `.xlsx` artifacts for the HIV DAK.
**Audience:** national HIV program + digital health teams; the L2/L3 working groups.
**Scope (locked):** one decision-support table and one indicator, authored end-to-end as worked examples.
**How to use this:** Parts A–C are the method (what an L2 DAK is, the adopt-and-adapt process, the authoring conventions). Parts D–E are the two worked artifacts. Part F is the validation checklist and pitfalls. Part G is the open items to settle with the room. Appendix = evidence base and confidence.

> **Evidence note.** The WHO methodology and authoring conventions below are verified against WHO primary sources (SMART Guidelines IG Starter Kit v2.0.0; WHO HIV DAK 2nd ed.; HIV IG v1.0.0). The **Ethiopia specifics** are now read directly from the **localized data dictionary**, diffed row-by-row against the WHO default — see the companion **`REPORT-Ethiopia-DAK-adaptation.md`** for the full delta (298 added, 204 removed, 1,124 modified elements). What remains `[confirm: ETH]` is narrower: cross-checking specific changes against current national guidelines.

---

## Part A — The premise: the adaptation already exists; review, wire, and validate it

WHO publishes the HIV guidance as a **Digital Adaptation Kit (DAK)** — software-neutral documentation that distils clinical, public-health and data-use guidance into a form digital systems can implement. WHO's DAK outputs are **intentionally generic and meant to be contextualized**; the recommended workflow is *adopt the WHO DAK, then adapt its content to local needs* rather than authoring from scratch.

**Ethiopia has already done much of that adaptation.** The localized data dictionary differs from the WHO default by **298 added, 204 removed, and 1,124 modified data elements** (full delta in `REPORT-Ethiopia-DAK-adaptation.md`): a new **Surveillance** module, **national PrEP/PEP/ART regimens** (incl. injectable Lenacapavir), a **maternal testing algorithm**, **"Invalid" results** and **retest-before-ART** steps, and **updated value sets** across registration, regimens, and disaggregators.

- So the session's job is **not** to author the ~20% from a blank generic DAK — it is to **review** what was changed, **wire** the many added elements that aren't yet connected to a decision table or indicator, **re-derive** the affected logic, and **validate** it.
- Where Ethiopia changed a value set, the artifacts simply **adopt the localized values** — treated the same as any other modification.
- The two worked examples below are reframed accordingly: each shows **completing and wiring the existing Ethiopia changes**, in the WHO formats, so the output drops into the national DAK and then the L3 IG.

## Part B — What an L2 DAK contains, and where our two artifacts live

The L2 DAK has **nine components**, delivered as a narrative PDF plus four Excel web annexes:

| Web annex (.xlsx) | Component | This is where… |
|---|---|---|
| **Annex A** | Core data elements (data dictionary) | where every input/output value lives |
| **Annex B** | Decision-support logic | **our decision table is authored** |
| **Annex C** | Indicators & performance metrics | **our indicator is authored** |
| **Annex D** | Functional / non-functional requirements | system requirements |

(Other components: health interventions/recommendations, generic personas, user scenarios, business processes/workflows, scheduling logic. Note: some older WHO material lists *eight* components, folding scheduling into decision support — participants may have seen that framing.)

**The binding rule that connects the three annexes:** *collect once, use many times.* Every value used by a decision table or an indicator **must exist as a data element in Annex A**. In the attached dictionary this is explicit — each data element row carries `Linkages to Decision Support Tables` and `Linkages to Aggregate Indicators`. That linkage is the backbone we author against.

**Where it goes next (L2 → L3):** L3 authoring takes the L2 as input and produces FHIR artifacts that correspond to it — **decision tables → `PlanDefinition` + `Library` + CQL**; **indicators → FHIR `Measure` + CQL**. So a clean L2 artifact is the direct, traceable input to fixing/building the L3 IG. WHO also recommends **tracking versions of L2 content when adapting locally**, to record changes and assess their impact (provenance).

## Part C — The authoring conventions (use these exactly)

### C1. Decision-support table (Annex B)
- Tables follow the **DMN (Decision Model and Notation)** standard, authored in a spreadsheet.
- Column structure used by the WHO HIV IG: **`Rule ID` · `Condition Inputs` (one variable-named column per input) · `Output Type` · `Action` · `Guidance` · `Annotations` · `Reference(s)`**.
- Declare a **Hit Policy** (e.g., *Rule order* / *First*) so the engine knows how rules are evaluated.
- Use explicit operators in cells: `=`, `IN`, `>=`, `<`, `is NULL`, `=True/=False`.
- **Guardrail: avoid tables with 10+ inputs** — split into separate tables. (Directly relevant to refactoring complex/buggy tables.)
- Every input/output references an **Annex A data element** (coded value sets, not free text).

### C2. Indicator (Annex C)
Author each indicator with these L2 template fields: **short name · indicator definition · category · what it measures · rationale · numerator definition · numerator calculation · denominator definition · denominator calculation · disaggregation description · reference** (plus DAK ID and the WHO Strategic Information reference number).
- Numerator and denominator are built **only from data elements already in Annex A**.
- Prioritize indicators **derivable from routine primary-care data** (collect once, use many).
- **Computability test before you start (critical):** some HIV indicators are *not* computable from DAK routine data and must not be authored as clinical logic — e.g. condoms distributed (IND.1), needles/syringes (IND.10), condom use (IND.17), key populations who know status (IND.26), KP living with HIV on ART (IND.36) are labeled in the IG as *"Not included in DAK; survey-based"* or *"…from multiple data sources."* The authorable pattern is a **count over coded data elements** — model example: **HIV.IND.2 / PRV.2 (PrEP recipients)** = `COUNT of clients with "PrEP for HIV prevention" prescribed in the reporting period`, denominator = 1.

> **ID crosswalk caveat.** The DAK data dictionary uses family IDs (`HTS.*`, `ART.*`, `VER.*`…); the L3 IG renumbers indicators as `HIV.IND.N`. The exact published `HIV.IND` inventory/numbering (including whether the remediation plan's IND.23, 97–100 exist) was **not verified** — check the live indicators page before relying on a specific number.

---

## Part D — Worked artifact #1 (decision support): `HIV.B7.DT` — National HIV testing algorithm

**Why this one.** It is the single most country-specific artifact in the DAK, foundational (every diagnosis depends on it), and **Ethiopia has already changed it** — `HIV.B7.DT` is among the most-adapted tables in the dictionary (**+21 elements, −1, 31 modified**). Ethiopia added an **"Invalid" assay-result** value, **verification-on-discordance** and **retest-before-ART** steps (the latter wired to `HIV.D12.DT`), and a **maternal-serology reuse** in PMTCT (`HIV.E.ET.DE200–220`, wired to `B7`/`E4`). Several of those additions still have **blank linkage cells** — added as data but not yet connected to the table. So this example is **wiring and reconciling the existing Ethiopia changes**, not authoring from scratch — which also fixes the real L3 gap (the smart-hiv B7 logic is hard-coded non-functional: `define "Non-reactive result": false`).

**Clinical-safety logic to PRESERVE (WHO baseline — do not lose in adaptation):**
- Everyone is tested on **Assay 1 (A1)**.
- **A1 non-reactive → report HIV-negative.**
- Reactive results proceed **A1 → A2 → A3** (serial).
- **Discrepant handling:** e.g., `A1+ ; A2−` → **repeat Assay 1**.
- **Inconclusive outcomes → schedule retest at visit date + 14 days.**
- (Infants <18 months are diagnosed by **virologic/EID** testing, not this serology table — route to the EID/indeterminate-results logic, HIV.E12.DT.)

**Decision table skeleton (Annex B format).** Hit policy: *Rule order*. Inputs are the assay-result data elements from Annex A (`HIV.B.DE94/97/100`); the output is the **HIV test result** element (`HIV.B.DE107`, coded HIV-positive / HIV-negative / HIV-inconclusive).

| Rule ID | A1 result | A2 result | A3 result | Output: HIV test result | Action / Guidance | Reference |
|---|---|---|---|---|---|---|
| B7-R1 | `= Non-reactive` | — | — | HIV-negative | Report negative; counsel on window period / re-test if recent exposure | WHO HTS 2019; `[confirm: ETH]` |
| B7-R2 | `= Reactive` | `= Reactive` | `= Reactive` | HIV-positive | **Verify** positive status before ART per policy; link to care/ART | WHO HTS 2019; `[confirm: ETH]` |
| B7-R3 | `= Reactive` | `= Reactive` | `= Non-reactive` | HIV-inconclusive | Retest at **visit date + 14 days** | WHO HTS 2019; `[confirm: ETH interval]` |
| B7-R4 | `= Reactive` | `= Non-reactive` | — | (discrepant) repeat A1 | Repeat Assay 1; if still discrepant → inconclusive → retest +14d | WHO HTS 2019 |

**Ethiopia adaptation slots — settle with the room `[confirm: ETH]`:**
1. **Which assays** are A1 / A2 / A3 (national product list), and is the strategy **serial** (as above) or any **parallel** step?
2. **Retest interval** — confirm Ethiopia uses 14 days for inconclusive.
3. **Verification testing** before ART initiation — national policy (WHO recommends re-testing to verify a positive status before ART).
4. **Entry points / who tests** (PITC, VCT, index, ANC, community) — affects the modality value set used by the indicator.
5. Age routing: confirm the <18-month EID handoff and self-test confirmatory path.

**L3 target:** `PlanDefinition` (HIVB7DT) + CQL `Library` — replacing the current non-functional logic; preserve the rules above so the safety behavior is not re-broken.

---

## Part E — Worked artifact #2 (indicator): HIV testing positivity (yield)

**Why this one.** Simple, high-value, computable from routine data, and it runs off the **same element** the B7 table produces (the HIV test result) — so one piece of contextualized logic drives both the point-of-care result and the report. Two Ethiopia-specific wrinkles make it a real worked example, not a copy:
- The HIV test result now **also lives in the new Surveillance module** (`HIV.Surveil.DE2`, wired to `HTS.2/3/7/8`). The example must decide the **source of truth** the indicator reads (HTS visit vs Surveillance).
- Several referenced elements **moved or were removed** (e.g. `Date HIV test results returned`), and disaggregation uses the **localized value sets** — re-point to the localized/Surveillance elements and adopt the national values.

**Definition (Annex C fields):**
- **Short name:** HIV testing positivity (yield).
- **What it measures / rationale:** the share of HIV tests that return positive — testing efficiency and case-finding yield; guides where to target testing.
- **Numerator definition:** number of individuals with **HIV test result = HIV-positive** (`HIV.B.DE107`, the B7 outcome) during the reporting period.
  **Numerator calculation:** `COUNT of clients where [HIV test result] = HIV-positive AND [HIV test date] in reporting period`.
- **Denominator definition:** number of individuals **tested for HIV** during the period.
  **Denominator calculation:** `COUNT of clients where [HIV test performed/date] in reporting period`.
- **Disaggregation:** **age band — include <1 and 1–14 explicitly** (the pediatric case-finding gap), plus 15–19/20–24/25+; **sex**; **testing modality/entry point**; location. (KP disaggregation is sensitive and partly survey-bound — handle separately; do not fold KP-status indicators into this routine count.)

**Simplest authorable variant** (mirrors the IND.2 count pattern): *number of individuals newly diagnosed HIV-positive in the period*, denominator = 1 — useful if the team wants to start from a pure count before adding the denominator.

**Maps to what Ethiopia reports `[confirm: ETH]`:** PEPFAR MER **`HTS_TST` / `HTS_TST_POS`**; DHIS2/HMIS HTS testing+positivity. Confirm the exact national definitions/disaggregations so the contextualized indicator reconciles with existing numbers (a strong validation step — the new indicator should reproduce known totals).

**L3 target:** FHIR `Measure` + CQL (shared `IndicatorLogic` library).

---

## Part F — Contextualization pitfalls & validation checklist

Run every authored artifact through this before calling it done:

- [ ] **Every input/output is an Annex A data element** (coded value set, not free text). Add missing elements to the dictionary first.
- [ ] **Computability:** the indicator's numerator and denominator come from routine DAK data — not a survey or external aggregate (the IND.1/10/17/26/36 trap).
- [ ] **≤10 inputs** per decision table; split if larger.
- [ ] **Hit policy and operators** declared explicitly.
- [ ] **Preserve safety logic** (B7: A1− → negative; serial A1→A2→A3; discrepant repeat-A1; 14-day retest).
- [ ] **Avoid the documented smart-hiv bugs** when adapting related logic: key-population stratifier must test the data element's **value, not its code** (`O.value`, not `O.code`); PEP vs PrEP must use the **correct dose/threshold** (don't apply a methadone threshold to buprenorphine, etc.); watch **operator precedence** in numerators; keep Measure↔Library **population names** consistent (`Numerator`/`Denominator`).
- [ ] **Disaggregation** matches national reporting (so the indicator reconciles with HMIS/MER).
- [ ] **Provenance:** record what diverged from the WHO DAK and why (version note) — feeds the L2→L3 change log.
- [ ] **Reconcile a known total** (e.g., last quarter's HTS_TST_POS) against the authored indicator as a validity check.

## Part G — Open items to resolve with the room

Now grounded in the actual adaptation (see `REPORT-Ethiopia-DAK-adaptation.md` and the work plan in `IMPACT-ANALYSIS-DD-to-DT-indicators.md`):
1. **Wiring gaps** — 233 added `.ET` elements have blank linkage cells. Connect each to its decision table / indicator (value-options inherit the parent's linkage; the impact analysis lists the targets).
2. **Update Annexes B and C** — they are still the WHO defaults; apply the Annex-A delta to the decision tables and indicators (this is the workshop's core output).
3. **Re-derive the national-regimen tables** — `HIV.C23.DT` (PrEP/PEP) and `HIV.D21.x` (ART / drug interactions) to the national formulary (incl. injectable Lenacapavir in `PRV.*`).
4. **Govern the new Surveillance module** — who owns it; its relationship to routine HMIS/MER; whether it is the indicator source of truth.
5. **Terminology bindings** for the coded elements (ICD-11/LOINC/SNOMED/national) and confirm the live `HIV.IND` numbering.

---

## Appendix — Evidence base & confidence

**Verified (WHO primary sources):** the nine-component / four-annex DAK structure; adopt-and-adapt premise and replicable process; DMN decision-table conventions (columns, hit policy, ≤10-input guardrail); indicator template fields and "collect once, use many"; the non-computable survey-based indicators (IND.1/10/17/26/36); the count-based authorable pattern (IND.2/PRV.2); the named decision tables (B7, E4, E12, D17, D21.1); B7's A1/A2/A3 + discrepant + 14-day-retest logic; the L2→L3 mapping (PlanDefinition/Library/CQL; Measure/CQL); version/provenance recommendation.

**To confirm against Ethiopian sources (`[confirm: ETH]`):** national testing assays/intervals; ART/PMTCT/EID/PrEP specifics; the 52% pediatric-diagnosed figure; Ethiopia's actual MER/HMIS reporting set and definitions; terminology bindings; the live `HIV.IND` inventory.

**Key references**
- WHO SMART Guidelines IG Starter Kit v2.0.0 — L2 authoring overview & DAK authoring: https://smart.who.int/ig-starter-kit/l2_authoring_overview.html · https://smart.who.int/ig-starter-kit/l2_dak_authoring.html · authoring overview (L2→L3): https://smart.who.int/ig-starter-kit/authoring_overview.html
- WHO HIV DAK, 2nd ed. (Dec 2023): https://www.who.int/publications/i/item/9789240085138
- WHO HIV IG v1.0.0 — decision logic: https://smart.who.int/hiv/decision-logic.html · indicators: https://smart.who.int/hiv/indicators.html · example indicator logic: https://smart.who.int/hiv/Library-HIVIND2Logic.html
- SMART Guidelines Pathfinder study (incl. Ethiopia), JMIR Med Inform 2025: https://medinform.jmir.org/2025/1/e58858
- WHO Consolidated Guidelines on HIV Testing Services (2019) — testing-strategy basis for B7.
- Ethiopia national HIV / PMTCT guidance (validate specifics): Ethiopia HIV guideline (policyvault.africa ETH32); National Guideline for PMTCT of HIV; Ethiopia PEPFAR Strategic Direction Summary 2023.
- Companion: `smart-hiv` IG `REMEDIATION-PLAN.md` (gap/safety items referenced in Parts D–F).