Combined Outcomes Rule
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: COMBINED_OUTCOME rule for assigning LIMS outcomes based on well observations Domain: RULES-COMBOUT Precedence: Before RQUAL
Statement
The system shall evaluate well observation results against configured Combined Outcome mappings to assign LIMS outcomes and error codes.
The rule matches observations based on role, classification, CT values, quantities, discrepancy status, and IC failure flags. When multiple outcomes match, the lowest group number wins. Multi-mix outcomes support patient matching across wells.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-COMBOUT-001 | Matches observations to combined outcomes and resolves conflicts | HIGH | Draft |
| REQ-RULES-COMBOUT-002 | Evaluates multi-mix outcomes across same-patient wells | HIGH | Draft |
| REQ-RULES-COMBOUT-003 | Applies CLS discrepancy as a combined outcome condition | MEDIUM | Draft |
| REQ-RULES-COMBOUT-004 | Applies CT discrepancy as a combined outcome condition | MEDIUM | Draft |
Key Integration Points: Well/Observation data, Kit configuration, LIMS outcomes/errors
Rule Summary
| Property | Value |
|---|---|
| Name | COMBINED_OUTCOME |
| Precedence | Before RQUAL |
| Triggers | When evaluating configured combined outcome mappings |
| Output | Sets LIMS outcome and error codes on well/target |
Rule Flowchart (Illustrative)
This diagram illustrates the core matching logic. Multi-mix evaluation and history lookups follow additional paths not shown.
Definitions
| Term | Definition |
|---|---|
| Combined Outcome | A configured mapping specifying conditions for assigning a LIMS outcome |
| CLS | Classification — categorical result (Pos, Neg, Amb, etc.) |
| CT | Cycle Threshold — PCR amplification cycle at detection |
| Mix | A specific reagent mixture used in testing |
| Observation | Measurement result for a specific target in a well |
| Well | A physical location on a plate containing a sample |
| Accession | Unique patient/sample identifier for cross-well matching |
| Group | Priority ordering for conflict resolution (lower = higher priority) |
| IC_FAILED | Internal Control failure flag on an observation |
Assumptions
- The COMBINED_OUTCOME rule executes before the RQUAL rule in precedence order
- Well observations have been calculated prior to rule execution
- Combined outcome configurations are valid and loaded
- LIMS outcome codes are unique across all configured outcomes
- For multi-mix features, the accession field is populated for patient identification
- Historical run data is accessible when allow_other_runs_to_be_used is enabled
Requirements
Core Matching (REQ-RULES-COMBOUT-001)
FR-COMBOUT-001: Evaluate Well Results Against Combined Outcome Configurations
The system shall evaluate well observation results against configured Combined Outcome mappings to assign LIMS outcomes and error codes, resolving conflicts using the group property (lowest group number wins).
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | Well observations (role, classification, CT, quantity, problems) | PCR analysis |
| Input | Combined outcome mappings, target results | Kit configuration |
| Output | LIMS outcome code | Well record |
| Output | Error code | Well and target records |
Acceptance Criteria
Matching Scope and Role:
- Check well results against each Combined Outcome configuration
- Outcomes (LIMS) codes shall be unique, even when they share the same outcome message
- Match only when the Combined Outcome role matches the observation role
- When the Combined Outcome role does not match, do not assign that outcome
- When a matching Combined Outcome is an Error type, set the error code on the well and target
- When an Error outcome is assigned, leave LIMS null
Result and Classification Matching:
- Result of "Any" matches any observation
- Result of "Classification/Discrepancy" matches when the observation has a CLASSIFICATION problem
- Exact classification matches when result equals observation.final_cls
IC_FAILED Handling:
| IC_FAILED Config | Observation IC_FAILED | Result |
|---|---|---|
| true | present | Assign error |
| true | absent | Do not assign error |
| false | present | Do not assign error |
| false | absent | Do not assign error |
Quantity Range Matching:
- Quantity matches when min_quantity/max_quantity are both null or final_quantity is within bounds
- Null quantity boundaries are treated as unbounded
- When max_quantity is set and final_quantity exceeds it, another rule determines the outcome
CT Range Matching:
- CT matches when min_ct/max_ct are both null or final_ct is within bounds
- When both CT and quantity conditions are defined, both must match for the same observation
Conflict Resolution and Precedence:
- When an observation matches more than one Combined Outcome, sort by group ascending and use the lowest group number
- Rule programmatic name is COMBINED_OUTCOME
- Rule executes before RQUAL in precedence order
Error Handling
- No matching combined outcome: allow the well to fall through to subsequent rules
- Multiple outcomes match: select the outcome with lowest group number
Trace: Source: 3.0.0-Combine Outcomes Rule (Rows 1-8) | Jira: BT-3072, BT-3585, BT-3850, BT-3876, BT-3386 | Tests: BT-406, BT-407, BT-3661, BT-3660, BT-3879, BT-3885, BT-3543 | Evidence: Combined Outcomes from CLS results.pdf, Combined Outcomes from CT results.pdf
Multi-Mix Outcomes (REQ-RULES-COMBOUT-002)
FR-COMBOUT-002: Support Multi Mix Combined Outcomes
The system shall evaluate outcomes that depend on results from multiple mixes for the same patient, aggregating well results across mixes identified by accession and optionally considering wells from historical runs.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | Current run wells (mix, accession, type) | Run data |
| Input | Historical run wells (outcome, mix, dates) | History store |
| Input | Combined outcome mix results | Kit configuration |
| Output | Mix-level outcomes | Well records |
Acceptance Criteria
Scope and Patient Matching:
- Trigger only for Sample-typed wells
- Non-sample wells (e.g., NEC) do not receive outcomes from this rule
- Mix results are satisfied only by wells belonging to the same patient
- Patient matching uses the accession field; wells with different accessions do not satisfy each other's mix requirements
Mixes Missing Logic:
- When mixes_missing is false, mix results marked mix_missing: true are not satisfied by wells present in the run
- When mixes_missing is false, all mix results not marked mix_missing are satisfied by wells
History Inclusion:
- When allow_other_runs_to_be_used is true, wells from history runs are considered for mix result satisfaction
- When allow_other_runs_to_be_used is false, only wells from the current run are considered
Required History Outcomes and Selection:
- When required_history_outcomes is configured, history wells must have a matching outcome to satisfy the mix result
- If a history well outcome does not match the required outcome, it does not satisfy that mix result
- Only the most recent history well for the patient is evaluated when required_history_outcomes is used
- Most recent history well is determined by: same mix + same accession, ordered by extraction date (descending), then run file creation date (descending)
- Target results must also be satisfied by the most recent history well (e.g., final_cls must match)
Repeat Well Verification (IS_REPEAT):
- When a mix result is marked as is_repeat: true, the system shall verify both current AND historical well conditions
- The current well must have matching results (classification, CT, quantity) as specified in the mix result configuration
- A matching historical well must exist from a previous run for the same patient with the same outcome code
- The historical well must satisfy the required target results (e.g., final_cls must match the configured result)
- If no matching historical well exists, the combined outcome is not assigned even if the current well matches
- Historical well lookup uses the most recently uploaded well for the mix, determined by runfile_created_at timestamp
Well Selection Priority (USE_LATEST_UPLOADED_WELL):
- When use_latest_uploaded_well is true, the system shall prioritize wells from the most recently uploaded run
- Selection order: (1) Most recently uploaded run first, (2) Same run, (3) Nearest runs by extraction date
- Most recent is determined by well creation timestamp; wells uploaded after the current well are selected first
- When use_latest_uploaded_well is false, selection order is: (1) Same run, (2) Nearest runs by extraction date
- This prioritization affects which historical well is selected when multiple wells could satisfy a mix result
Specimen-Aware Outcome Matching (SPECIMEN):
- When the combined outcome has a specimen configured AND use_sample_type is enabled in client configuration, the system shall filter wells by specimen type
- Only wells with the same specimen as the combined outcome configuration are considered for matching
- Specimen filtering applies to both current run wells and historical run wells
- When specimen is null on the combined outcome OR use_sample_type is disabled, specimen filtering is bypassed (all specimens match)
- Same-run well candidates are filtered by specimen before mix result satisfaction is evaluated
- Historical well candidates are filtered by specimen before most-recent selection occurs
Mix-Level Outcomes:
- When a matching Combined Outcome has mix-level outcomes configured, each well receives the outcome specified for its mix
- Different wells from the same patient may receive different outcomes based on their mix assignment
Error Handling
- No wells found for a required mix: do not assign the multi-mix outcome
- Patient accession mismatch: do not consider wells from different patients
- History well has wrong outcome: do not satisfy the mix result with that history well
Assumptions
- The accession field is populated for all sample wells requiring multi-mix evaluation
- Historical run data is accessible when allow_other_runs_to_be_used is enabled
Trace: Source: 3.0.0-Combined Outcome Rule - Support Multi Mix Combined Outcomes (Rows 1-7) | Jira: BT-4070 | Epic: BT-4051 | Tests: [Pending]
Discrepancy Checks (REQ-RULES-COMBOUT-003 & 004)
FR-COMBOUT-003: Evaluate CLS Discrepancy Status in Combined Outcome Matching
The system shall evaluate classification discrepancy status as a matching condition for Combined Outcomes, following the same discrepancy determination logic as the WDCLS rule.
Acceptance Criteria
Discrepancy Evaluation:
- Evaluate the path: combined_outcome -> mix_result -> target_result -> cls_discrepancy_required
- Observation CLS discrepancy determination follows the same logic as the WDCLS rule
CLS Discrepancy Matching:
| cls_discrepancy_required | has_cls_discrepancy | Result |
|---|---|---|
| true | true | Assign combined outcome |
| true | false | Do not assign combined outcome |
| false | true | Do not assign combined outcome |
| false | false | Assign combined outcome |
| Any | true/false | Assign combined outcome |
Scope and Limitations:
- CLS discrepancy evaluation occurs only on wells within the current run
- Multi-run combined outcome feature is disabled for CLS discrepancy checking
Error Handling
- Multi-run CLS discrepancy check attempted: evaluate only current run wells (technical limitation)
Trace: Source: 3.0.0-CLS Discrepant Check (Rows 1-2) | Jira: BT-5226 | Epic: BT-5225 | Tests: BT-5228 | Related: WDCLS rule (discrepancy calculation)
FR-COMBOUT-004: Evaluate CT Discrepancy Status in Combined Outcome Matching
The system shall evaluate cycle threshold (CT) discrepancy status as a matching condition for Combined Outcomes, following the same discrepancy determination logic as the WDCT rule.
Acceptance Criteria
Discrepancy Evaluation:
- Evaluate the path: combined_outcome -> mix_result -> target_result -> ct_discrepancy_required
- Observation CT discrepancy determination follows the same logic as the WDCT rule
CT Discrepancy Matching:
| ct_discrepancy_required | has_ct_discrepancy | Result |
|---|---|---|
| true | true | Assign combined outcome |
| true | false | Do not assign combined outcome |
| false | true | Do not assign combined outcome |
| false | false | Assign combined outcome |
| Any | true/false | Assign combined outcome |
Scope and Limitations:
- CT discrepancy evaluation occurs only on wells within the current run
- Multi-run combined outcome feature is disabled for CT discrepancy checking
Error Handling
- Multi-run CT discrepancy check attempted: evaluate only current run wells (technical limitation)
Trace: Source: 3.0.0-CT Discrepant Check (Rows 1-2) | Jira: BT-5308 | Epic: BT-5307 | Tests: [Pending] | Related: WDCT rule (discrepancy calculation)
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
combined_outcome.group | N/A | Priority ordering for conflict resolution (lower = higher priority) | REQ-RULES-COMBOUT-001 |
combined_outcome.ic_failed | false | Whether IC_FAILED status triggers error outcome | REQ-RULES-COMBOUT-001 |
combined_outcome.min_quantity | null | Lower bound for quantity matching (null = unbounded) | REQ-RULES-COMBOUT-001 |
combined_outcome.max_quantity | null | Upper bound for quantity matching (null = unbounded) | REQ-RULES-COMBOUT-001 |
combined_outcome.min_ct | null | Lower bound for CT matching (null = unbounded) | REQ-RULES-COMBOUT-001 |
combined_outcome.max_ct | null | Upper bound for CT matching (null = unbounded) | REQ-RULES-COMBOUT-001 |
combined_outcome.mixes_missing | false | Whether to check for absence of expected mixes | REQ-RULES-COMBOUT-002 |
combined_outcome.allow_other_runs_to_be_used | false | Whether to consider historical run wells | REQ-RULES-COMBOUT-002 |
combined_outcome.required_history_outcomes | [] | List of required outcomes for history well matching | REQ-RULES-COMBOUT-002 |
mix_result.is_repeat | false | Whether to require matching historical well with same outcome | REQ-RULES-COMBOUT-002 |
mix_result.use_latest_uploaded_well | false | Whether to prioritize most recently uploaded well for history lookup | REQ-RULES-COMBOUT-002 |
combined_outcome.specimen | null | Specimen type filter for outcome matching (null = any specimen) | REQ-RULES-COMBOUT-002 |
target_result.cls_discrepancy_required | Any | CLS discrepancy matching condition (true/false/Any) | REQ-RULES-COMBOUT-003 |
target_result.ct_discrepancy_required | Any | CT discrepancy matching condition (true/false/Any) | REQ-RULES-COMBOUT-004 |
Open Questions
| ID | Question | Source | Owner | Date Raised |
|---|---|---|---|---|
| OQ-001 | No UI detail specified in source material; confirm none is required for this backend rule. | UI Detail | @tbd | 2026-01-22 |
Notes
- Rule programmatic name: COMBINED_OUTCOME
- Referenced rules: RQUAL (lower precedence), WDCLS (CLS discrepancy calculation), WDCT (CT discrepancy calculation)
- Performance optimization for large runfiles (>384 wells) may be relevant for multi-mix evaluation
- The multi-run feature for CLS and CT discrepancy checks is temporarily disabled due to technical limitations
Implementation (Illustrative)
| Component | Location |
|---|---|
| Rule Class | Analyzer/Rules/CombinedOutcomeRule.php |
| Multi-well Rule | Analyzer/Rules/MultipleWellsCombinedOutcomeRule.php |
| Single-well Rule | Analyzer/Rules/SingleWellCombinedOutcomeRule.php |
| Outcome Setting | Analyzer/Rules/Concerns/CombinedOutcomes/SetOutcomeToWell.php |
| Satisfaction Check | Analyzer/Rules/Concerns/CombinedOutcomes/SatisfiesCombinedOutcome.php |
| Well Finder (IS_REPEAT, USE_LATEST) | Analyzer/Rules/Concerns/CombinedOutcomes/MatchingWellFinderForCombinedOutcome.php |
| Mix Results Check | Analyzer/Rules/Concerns/CombinedOutcomes/HasWellsForAllRequiredMixResultsAndNotForAnyRejectedMixResults.php |
| CLS Discrepancy | Analyzer/Rules/Concerns/CombinedOutcomes/CheckCLSDiscrepancy.php |
| CT Discrepancy | Analyzer/Rules/Concerns/CombinedOutcomes/CheckCTDiscrepancy.php |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-COMBOUT-001 | Core Combined Outcome Matching | Test | CombinedOutcomeRule | BT-406, BT-407, BT-3661, BT-3660, BT-3879, BT-3885, BT-3543 | Draft |
| REQ-RULES-COMBOUT-002 | Multi Mix Combined Outcomes | Test | MultipleWellsCombinedOutcomeRule | [Pending] | Draft |
| REQ-RULES-COMBOUT-003 | CLS Discrepancy Check | Test | CheckCLSDiscrepancy | BT-5228 | Draft |
| REQ-RULES-COMBOUT-004 | CT Discrepancy Check | Test | CheckCTDiscrepancy | [Pending] | Draft |
Acceptance Tests
Test: REQ-RULES-COMBOUT-001
Test: Role Mismatch
Given: client configuration with role: NEC, cls: pos, min_ct: 40, max_ct: 42
And: well with observation role: PEC, cls: pos, ct: 41
When: well is evaluated through combined outcome rule
Then: well shall NOT receive the outcome from the combined outcome
Test: Role Match
Given: client configuration with role: PEC, cls: pos, min_ct: 40, max_ct: 42
And: well with observation role: PEC, cls: pos, ct: 41
When: well is evaluated through combined outcome rule
Then: well shall receive the outcome from the combined outcome
Test: Error Outcome Assignment
Given: Combined Outcome with role: Patient, type: Error, well error code: Error A
And: Target A configured with cls: Pos, min_ct: 42, max_ct: 45
And: Target B configured with cls: Any
And: Well with Observation (Target A) role: Patient, cls: Pos, ct: 44
And: Well with Observation (Target B) cls: Neg
When: well is evaluated through combined outcome rule
Then: Well error code shall be "Error A"
And: Well LIMS shall be null
Test: IC Failed true with IC_FAILED problem
Given: Combined Outcome with Well Error Code: Example Error, IC Failed: true
And: Well with Observation having problems: IC_FAILED
When: well is evaluated through combined outcome rule
Then: well shall receive error with Error Code: Example Error
Test: IC Failed true without IC_FAILED problem
Given: Combined Outcome with Well Error Code: Example Error, IC Failed: true
And: Well with Observation having problems: <empty>
When: well is evaluated through combined outcome rule
Then: well shall NOT receive error
Test: IC Failed false with IC_FAILED problem
Given: Combined Outcome with Well Error Code: Example Error, IC Failed: false
And: Well with Observation having problems: IC_FAILED
When: well is evaluated through combined outcome rule
Then: well shall NOT receive error
Test: IC Failed false without IC_FAILED problem
Given: Combined Outcome with Well Error Code: Example Error, IC Failed: false
And: Well with Observation having problems: <empty>
When: well is evaluated through combined outcome rule
Then: well shall NOT receive error
Test: Quantity within range (both bounds)
Given: Observation with final_quantity: 1000
And: Combined Outcome with min_quantity: 900, max_quantity: 1000, lims_status: DETECTED
When: well is evaluated through combined outcome rule
Then: well shall have DETECTED lims status
Test: Quantity above min (no max)
Given: Observation with final_quantity: 1000
And: Combined Outcome with min_quantity: 900, max_quantity: null, lims_status: DETECTED
When: well is evaluated through combined outcome rule
Then: well shall have DETECTED lims status
Test: No quantity bounds (matches any)
Given: Observation with final_quantity: 1000
And: Combined Outcome with min_quantity: null, max_quantity: null, lims_status: DETECTED
When: well is evaluated through combined outcome rule
Then: well shall have DETECTED lims status
Test: Quantity exceeds max
Given: Observation with final_quantity: 1000
And: Combined Outcome with min_quantity: null, max_quantity: 999, lims_status: DETECTED
When: well is evaluated through combined outcome rule
Then: well shall NOT receive DETECTED status
And: another rule shall determine the outcome
Test: Combined CT + Quantity conditions not met
Given: Observation with final_quantity: 1000, final_ct: 30
And: Combined Outcome with min_ct: 31, max_ct: null, min_quant: 2000, max_quant: null, lims_status: DETECTED
When: well is evaluated through combined outcome rule
Then: well shall NOT receive outcome DETECTED
Test: Multiple Match Resolution
Given: Combined Outcome 1 with target: Target A, result: Pos, group: 2, lims status: DETECTED
And: Combined Outcome 2 with target: Target A, result: Pos, group: 1, lims status: NOT DETECTED
And: Well with Observation target: Target A, final cls: Pos
When: well is evaluated through combined outcome rule
Then: well shall have NOT DETECTED lims status (group 1 < group 2)
Test: REQ-RULES-COMBOUT-002
Test: Sample Type Filter
Given: outcome mapping A with outcome: LIMS A, mix results: [mix result A]
And: outcome mapping B with outcome: LIMS B, mix results: [mix result A, mix result B]
And: well with mix: Mix A, type: Nec (non-sample)
When: well is analyzed through rule
Then: well lims shall be null (not triggered for non-sample)
Test: Same Patient Requirement - Match
Given: outcome mapping with mix results: [Mix A, Mix B]
And: run with well A: accession A, mix Mix A
And: run with well B: accession A, mix Mix B
When: well A is evaluated
Then: well A shall receive outcome (same patient)
Test: Same Patient Requirement - Mismatch
Given: outcome mapping with mix results: [Mix A, Mix B]
And: run with well A: accession A, mix Mix A
And: run with well B: accession B, mix Mix B
When: well A is evaluated
Then: well A shall NOT receive outcome (different patient)
Test: Mixes Missing Logic - Expected Absence
Given: outcome mapping with mixes_missing: false
And: mix results: A (mix A, mix_missing: false), B (mix B, mix_missing: true), C (mix C, mix_missing: false)
And: run with wells: [Mix A, Mix C] (Mix B absent)
When: well A is evaluated
Then: well A shall receive outcome (missing mix B is expected)
Test: Mixes Missing Logic - Unexpected Presence
Given: outcome mapping with mixes_missing: false
And: mix results: A (mix A, mix_missing: false), B (mix B, mix_missing: true), C (mix C, mix_missing: false)
And: run with wells: [Mix A, Mix B, Mix C] (all present)
When: well A is evaluated
Then: well A shall NOT receive outcome (Mix B should be absent)
Test: History Runs Enabled
Given: outcome mapping with allow_other_runs_to_be_used: true, mix results: [mix A, mix B]
And: run A with well A (Mix B)
And: run B with well A (Mix A)
When: run B well A is analyzed
Then: run B well A shall receive outcome (uses history)
Test: History Runs Disabled
Given: outcome mapping with allow_other_runs_to_be_used: false, mix results: [mix A, mix B]
And: run A with well A (Mix B)
And: run B with well A (Mix A)
When: run B well A is analyzed
Then: run B well A shall NOT receive outcome (no history)
Test: Required History Outcomes - Match
Given: outcome mapping with required_history_outcomes: Lims A, mix results: [mix A, mix B]
And: run A with well A (Mix B, outcome: Lims A)
And: run B with well A (Mix A)
When: run B well A is evaluated
Then: run B well A shall receive outcome
Test: Required History Outcomes - Mismatch
Given: outcome mapping with required_history_outcomes: Lims A, mix results: [mix A, mix B]
And: run A with well A (Mix B, outcome: Lims B)
And: run B with well A (Mix A)
When: run B well A is evaluated
Then: run B well A shall NOT receive outcome (wrong history outcome)
Test: Most Recent History Selection - Correct
Given: outcome mapping with required_history_outcomes: LIMS A, mix results: [Mix A, Mix B]
And: run A with well A (Mix B, outcome: Lims B, e_date: 1)
And: run B with well A (Mix B, outcome: Lims A, e_date: 2) <- most recent
And: run C with well A (Mix A, e_date: 3)
When: run C well A is analyzed
Then: run C well A shall receive outcome (most recent has Lims A)
Test: Most Recent History Selection - Incorrect
Given: outcome mapping with required_history_outcomes: LIMS A, mix results: [Mix A, Mix B]
And: run A with well A (Mix B, outcome: Lims A, e_date: 1)
And: run B with well A (Mix B, outcome: Lims B, e_date: 2) <- most recent
And: run C with well A (Mix A, e_date: 3)
When: run C well A is analyzed
Then: run C well A shall NOT receive outcome (most recent has Lims B)
Test: Mix Level Outcomes
Given: outcome mapping with outcome: Detected (default)
And: mix results: A (mix A, outcome: Error A), B (mix B, outcome: Error B)
And: run with well A: mix Mix A
And: run with well B: mix Mix B
When: wells are evaluated
Then: well A outcome shall be Error A
And: well B outcome shall be Error B
Test: IS_REPEAT - History Well Exists with Matching Outcome
Given: outcome mapping with mix results: [mix A (is_repeat: true, result: Pos)]
And: run A with well A (Mix A, outcome: LIMS A, cls: Pos) from previous run
And: run B with well A (Mix A, cls: Pos) from current run
When: run B well A is evaluated
Then: run B well A shall receive outcome (history well has matching result)
Test: IS_REPEAT - No History Well
Given: outcome mapping with mix results: [mix A (is_repeat: true, result: Pos)]
And: run B with well A (Mix A, cls: Pos) from current run (no previous runs)
When: run B well A is evaluated
Then: run B well A shall NOT receive outcome (no history well exists)
Test: IS_REPEAT - History Well with Non-Matching Outcome
Given: outcome mapping with mix results: [mix A (is_repeat: true, result: Pos)]
And: run A with well A (Mix A, outcome: LIMS A, cls: Neg) from previous run
And: run B with well A (Mix A, cls: Pos) from current run
When: run B well A is evaluated
Then: run B well A shall NOT receive outcome (history well has different result)
Test: USE_LATEST_UPLOADED_WELL - Prioritizes Most Recent
Given: outcome mapping with use_latest_uploaded_well: true, mix results: [mix A, mix B]
And: run A with well A (Mix B, created_at: 2024-01-01)
And: run B with well A (Mix B, created_at: 2024-01-02) <- most recent
And: run C with well A (Mix A, created_at: 2024-01-03)
When: run C well A is evaluated for mix B satisfaction
Then: well from run B shall be selected (most recently uploaded)
Test: USE_LATEST_UPLOADED_WELL - Falls Back to Same Run
Given: outcome mapping with use_latest_uploaded_well: true, mix results: [mix A, mix B]
And: run A with well A (Mix A) and well B (Mix B) in same run
When: well A is evaluated
Then: well B from same run shall satisfy mix B (no future uploads available)
Test: USE_LATEST_UPLOADED_WELL Disabled - Uses Nearest by Extraction Date
Given: outcome mapping with use_latest_uploaded_well: false, mix results: [mix A, mix B]
And: run A with well A (Mix B, extraction_date: 2024-01-01, created_at: 2024-01-05)
And: run B with well A (Mix B, extraction_date: 2024-01-03, created_at: 2024-01-02)
And: run C with well A (Mix A, extraction_date: 2024-01-02)
When: run C well A is evaluated for mix B satisfaction
Then: well from run B shall be selected (nearest extraction date to run C)
Test: SPECIMEN - Filters Wells by Specimen Type
Given: client config with use_sample_type: true
And: outcome mapping with specimen: Serum, mix results: [mix A, mix B]
And: run with well A (Mix A, specimen: Serum) and well B (Mix B, specimen: Plasma)
When: well A is evaluated
Then: well A shall NOT receive outcome (well B has wrong specimen)
Test: SPECIMEN - Matching Specimen
Given: client config with use_sample_type: true
And: outcome mapping with specimen: Serum, mix results: [mix A, mix B]
And: run with well A (Mix A, specimen: Serum) and well B (Mix B, specimen: Serum)
When: well A is evaluated
Then: well A shall receive outcome (both wells have matching specimen)
Test: SPECIMEN - Bypassed When Disabled
Given: client config with use_sample_type: false
And: outcome mapping with specimen: Serum, mix results: [mix A, mix B]
And: run with well A (Mix A, specimen: Serum) and well B (Mix B, specimen: Plasma)
When: well A is evaluated
Then: well A shall receive outcome (specimen filtering bypassed)
Test: SPECIMEN - Bypassed When Not Configured
Given: client config with use_sample_type: true
And: outcome mapping with specimen: null, mix results: [mix A, mix B]
And: run with well A (Mix A, specimen: Serum) and well B (Mix B, specimen: Plasma)
When: well A is evaluated
Then: well A shall receive outcome (no specimen requirement on outcome)
Test: SPECIMEN - Filters History Wells
Given: client config with use_sample_type: true
And: outcome mapping with specimen: Serum, allow_other_runs_to_be_used: true, mix results: [mix A, mix B]
And: run A with well A (Mix B, specimen: Plasma) from previous run
And: run B with well A (Mix A, specimen: Serum) from current run
When: run B well A is evaluated
Then: run B well A shall NOT receive outcome (history well has wrong specimen)
Test: REQ-RULES-COMBOUT-003
Test: CLS discrepancy required true, has discrepancy true
Given: combined outcome with cls_discrepancy_required: true
And: observation with has_cls_discrepancy: true
When: observation is evaluated
Then: well shall receive the combined outcome
Test: CLS discrepancy required true, has discrepancy false
Given: combined outcome with cls_discrepancy_required: true
And: observation with has_cls_discrepancy: false
When: observation is evaluated
Then: well shall NOT receive the combined outcome
Test: CLS discrepancy required false, has discrepancy true
Given: combined outcome with cls_discrepancy_required: false
And: observation with has_cls_discrepancy: true
When: observation is evaluated
Then: well shall NOT receive the combined outcome
Test: CLS discrepancy required false, has discrepancy false
Given: combined outcome with cls_discrepancy_required: false
And: observation with has_cls_discrepancy: false
When: observation is evaluated
Then: well shall receive the combined outcome
Test: CLS discrepancy required Any, has discrepancy true
Given: combined outcome with cls_discrepancy_required: Any
And: observation with has_cls_discrepancy: true
When: observation is evaluated
Then: well shall receive the combined outcome
Test: CLS discrepancy required Any, has discrepancy false
Given: combined outcome with cls_discrepancy_required: Any
And: observation with has_cls_discrepancy: false
When: observation is evaluated
Then: well shall receive the combined outcome
Test: REQ-RULES-COMBOUT-004
Test: CT discrepancy required true, has discrepancy true
Given: combined outcome with ct_discrepancy_required: true
And: observation with has_ct_discrepancy: true
When: observation is evaluated
Then: well shall receive the combined outcome
Test: CT discrepancy required true, has discrepancy false
Given: combined outcome with ct_discrepancy_required: true
And: observation with has_ct_discrepancy: false
When: observation is evaluated
Then: well shall NOT receive the combined outcome
Test: CT discrepancy required false, has discrepancy true
Given: combined outcome with ct_discrepancy_required: false
And: observation with has_ct_discrepancy: true
When: observation is evaluated
Then: well shall NOT receive the combined outcome
Test: CT discrepancy required false, has discrepancy false
Given: combined outcome with ct_discrepancy_required: false
And: observation with has_ct_discrepancy: false
When: observation is evaluated
Then: well shall receive the combined outcome
Test: CT discrepancy required Any, has discrepancy true
Given: combined outcome with ct_discrepancy_required: Any
And: observation with has_ct_discrepancy: true
When: observation is evaluated
Then: well shall receive the combined outcome
Test: CT discrepancy required Any, has discrepancy false
Given: combined outcome with ct_discrepancy_required: Any
And: observation with has_ct_discrepancy: false
When: observation is evaluated
Then: well shall receive the combined outcome
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | Combined Outcomes Algorithm |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion - N/A, all requirements are distinct)
- UI details are fully demoted to non-normative section
- Configuration options are not encoded as requirements
- Acceptance criteria describe behavior, not UI mechanics
- Every requirement has acceptance criteria and source traceability
- Error handling addressed for I/O, validation, and external system requirements
- Open questions documented with owners assigned
- Consolidations documented in Reviewer Notes with reversibility info
- Module can survive a full UI redesign unchanged
- Refinements do not introduce new capabilities
- Traceability matrix is complete
Reviewer Notes
No Consolidation Applied
All four requirements in this domain represent genuinely distinct system capabilities:
| Requirement | Capability | Justification |
|---|---|---|
| REQ-RULES-COMBOUT-001 | Core Combined Outcome Matching | Primary rule logic with multiple matching conditions |
| REQ-RULES-COMBOUT-002 | Multi Mix Combined Outcomes | Distinct cross-well patient analysis capability |
| REQ-RULES-COMBOUT-003 | CLS Discrepancy Check | Specific condition type with own truth table |
| REQ-RULES-COMBOUT-004 | CT Discrepancy Check | Specific condition type with own truth table |
Rationale: This is a RULES domain where analytics precision is critical. Each requirement represents a distinct capability that can be independently tested and verified. Consolidation would obscure the specific behavior guarantees required for laboratory informatics accuracy.
Reversibility: Source requirements preserved 1:1.
- Source:
output/pilot/rules/rule-combine-outcomes/rule-combine-outcomes-restructured.md - Design:
output/pilot/rules/rule-combine-outcomes/sdd/rule-combine-outcomes-design.md