Combined Outcomes Control Rule

Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: COMBINED_OUTCOME_CONTROL rule for evaluating well observations with role verification and error handling Domain: RULES-COMBOUTCTRL Precedence: After COMBINED_OUTCOME (extends base combined outcome matching)

---

Statement

The system shall evaluate well observations against Combined Outcome Control configurations using role verification, error handling, and classification status matching to determine outcome assignments.

The rule extends base combined outcome matching with additional control conditions: role must match before any other criteria are evaluated, error-typed outcomes set error codes without setting LIMS status, and special result matching conditions support wildcards (Any), classification problems (Classification/Discrepancy), and exact classification matching. CT and quantity ranges provide optional boundary conditions.

---

Quick Reference

ID	Core Behavior	Priority	Status
REQ-RULES-COMBOUTCTRL-001	Evaluates observations with role verification, error handling, CT/quantity ranges	HIGH	Draft

Key Integration Points: Combined Outcome Rule (base), Well/Observation data, Run Target entities, Client Configuration

Rule Summary

Property	Value
Name	COMBINED_OUTCOME_CONTROL
Base Rule	COMBINED_OUTCOME
Triggers	When evaluating configured combined outcome control mappings
Output	Sets LIMS outcome, well error codes, or target error codes

---

Rule Flowchart (Illustrative)

This diagram illustrates the core matching logic. Role verification occurs first, followed by result matching, range checks, and outcome assignment. Error outcomes set error codes without LIMS status.

---

Definitions

Term	Definition
CLS	Classification - the categorical result of an observation (Pos, Neg, Amb)
CT	Cycle Threshold - PCR amplification cycle at which signal is detected
Combined Outcome	A configured mapping that assigns outcomes based on observation criteria
LIMS	Laboratory Information Management System status
NEC	Negative Extraction Control - a control well type
PEC	Positive Extraction Control - a control well type
Role	The control type designation for an observation (Patient, PEC, NEC, etc.)
Well	A physical location on a plate containing a sample
Classification/Discrepancy	An observation problem status indicating classification ambiguity

---

Assumptions

• Well observations have been processed by upstream rules before this rule executes
• Combined outcome configurations are defined in client configuration
• Observation roles are assigned during earlier processing stages
• The COMBINED_OUTCOME rule is available as the base matching mechanism

---

Requirements

Combined Outcome Control Matching (REQ-RULES-COMBOUTCTRL-001)

FR-COMBOUTCTRL-001: Evaluate Well Observations Against Combined Outcome Control Configurations

The system shall evaluate well observations against Combined Outcome Control configurations using role verification, error handling, and classification status matching to determine outcome assignments.

Inputs/Outputs

Direction	Data	Source/Target
Input	Well observations (role, classification, CT, quantity, problems)	PCR analysis
Input	Combined outcome control mappings	Client configuration
Output	LIMS outcome code	Well record
Output	Error code	Well and Run Target records

Acceptance Criteria

Role Verification (Gate):

• Verify that observation role matches the configured combined outcome role before assigning outcomes
• When combined outcome role differs from observation role, do NOT assign that outcome to the well
• When combined outcome role matches observation role, evaluate the well for that outcome (if other criteria match)
• Verify role matching before evaluating any other matching criteria

Result Matching Conditions:

• Support result matching condition result == Any that matches any observation regardless of classification
• Support result matching condition result == Classification/Discrepancy that matches observations with a CLASSIFICATION problem flag
• Support result matching condition result == observation.final_cls that matches observations where final classification equals the configured result
• Use the observation problems list to detect the CLASSIFICATION flag for Classification/Discrepancy matching
• Evaluate result matching in order: Any (wildcard), Classification/Discrepancy (problem flag check), specific classification (exact match)

Target Results (AND Logic):

• All target result conditions within a Combined Outcome shall be satisfied for the outcome to be assigned
• Multiple targets may use different result matching conditions within the same Combined Outcome
• Require all target results within a Combined Outcome to match for the outcome to be assigned (AND logic across targets)

CT Range Matching:

• When min_ct and max_ct are configured, observation CT value shall fall within the range (inclusive) for a match
• Null CT boundaries shall be treated as unbounded (no limit on that side)

Quantity Range Matching:

• When min_quant and max_quant are configured, observation quantity shall fall within the range for a match
• Null quantity boundaries shall be treated as unbounded
• CT and quantity conditions shall be combined with other matching criteria (role, result) using AND logic

Error Outcome Assignment:

• When matching Combined Outcome has type "Error", set the configured error code on the well
• When error outcome is assigned, well LIMS status shall remain null
• When Combined Outcome configuration includes a target error code, set that error on the corresponding Run Target
• Well error code and target error code may be different values within the same Combined Outcome configuration
• When an error-typed outcome is assigned, set well error codes but do not set LIMS status

Error Handling

• No matching combined outcome: allow the well to fall through to subsequent rules
• Role mismatch: skip evaluation of remaining criteria for that outcome

Trace: Source: 3.0.0-Combined Outcomes Control Rule (Rows 1-3) | Jira: BT-3557 (Epic), BT-3586 (Role Check), BT-3850 (Classification/Discrepancy) | Tests: BT-3661 (Rule Verification), BT-3879 (Classification/Discrepancy Verification) | Related: COMBINED_OUTCOME rule (base combined outcome matching)

---

Configuration Options

Option	Default	Description	Affects
role	(required)	The control role that observations must match (Patient, PEC, NEC, etc.)	REQ-RULES-COMBOUTCTRL-001
type	Normal	Outcome type - "Normal" sets LIMS status, "Error" sets error codes	REQ-RULES-COMBOUTCTRL-001
well_error_code	(conditional)	Error code to set on well when Error type outcome matches	REQ-RULES-COMBOUTCTRL-001
target_error	null	Optional error code to set on Run Target when Error type outcome matches	REQ-RULES-COMBOUTCTRL-001
min_ct	null	Minimum CT value for range matching (null = unbounded)	REQ-RULES-COMBOUTCTRL-001
max_ct	null	Maximum CT value for range matching (null = unbounded)	REQ-RULES-COMBOUTCTRL-001
min_quant	null	Minimum quantity value for range matching (null = unbounded)	REQ-RULES-COMBOUTCTRL-001
max_quant	null	Maximum quantity value for range matching (null = unbounded)	REQ-RULES-COMBOUTCTRL-001
result	(per target)	Result matching condition: Any, Classification/Discrepancy, or specific CLS	REQ-RULES-COMBOUTCTRL-001

---

Open Questions

ID	Question	Source	Owner	Date Raised
OQ-001	No UI specifications identified in source material; confirm none is required for this backend rule.	UI Detail	@tbd	2026-01-23

---

Notes

• Rule programmatic name: COMBINED_OUTCOME_CONTROL
• This rule is distinct from COMBINED_OUTCOME - it provides additional control conditions including role verification and error handling
• Related rules: COMBINED_OUTCOME (base combined outcome matching)
• The rule evaluates observations in sequence; first matching outcome is applied

---

Implementation (Illustrative)

Component	Location
Rule Class	Analyzer/Rules/CombinedOutcomeControlRule.php
Outcome Setting	Analyzer/Rules/Concerns/CombinedOutcomes/SetOutcomeToWell.php
Mix/Target Check	Analyzer/Rules/Concerns/CombinedOutcomes/HasMatchingMixResultsAndTargetResults.php

---

Traceability Matrix

Requirement	Title	Verification	Implementation	Test Cases	Status
REQ-RULES-COMBOUTCTRL-001	Evaluate Well Observations Against Combined Outcome Control Configurations	Test	CombinedOutcomeControlRule	BT-3661, BT-3879	Draft

---

Acceptance Tests

Test: REQ-RULES-COMBOUTCTRL-001

Back to requirement

Test: Role Mismatch - No Outcome Assignment

Given: Client configuration with:
  | Field | Value |
  | role | NEC |
  | cls | pos |
  | min_ct | 40 |
  | max_ct | 42 |
And: A well with observation:
  | Field | Value |
  | role | PEC |
  | cls | pos |
  | ct | 41 |
When: The Combined Outcome Control rule evaluates the well
Then: The well shall NOT receive the outcome from the combined outcome
And: The role mismatch (NEC != PEC) shall prevent outcome assignment

Test: Role Match - Outcome Assignment

Given: Client configuration with:
  | Field | Value |
  | role | PEC |
  | cls | pos |
  | min_ct | 40 |
  | max_ct | 42 |
And: A well with observation:
  | Field | Value |
  | role | PEC |
  | cls | pos |
  | ct | 41 |
When: The Combined Outcome Control rule evaluates the well
Then: The well shall receive the outcome from the combined outcome
And: The role match (PEC == PEC) shall allow outcome assignment

Test: Error Outcome - Well Error Only

Given: Combined Outcome configuration with:
  | Field | Value |
  | role | PEC |
  | type | Error |
  | well_error_code | Error A |
And: Target A configuration:
  | Field | Value |
  | cls | Pos |
  | min_ct | 42 |
  | max_ct | 45 |
And: Target B configuration:
  | Field | Value |
  | cls | Any |
And: A well with observations:
  | Observation | Role | Target | CLS | CT |
  | 1 | PEC | Target A | Pos | 44 |
  | 2 | - | Target B | Neg | null |
When: The Combined Outcome Control rule evaluates the well
Then: The well error_code shall be set to "Error A"
And: The well LIMS status shall be null

Test: Error Outcome - Well Error and Target Error

Given: Combined Outcome configuration with:
  | Field | Value |
  | role | PEC |
  | type | Error |
  | well_error_code | Error A |
  | target_error | Error B |
And: Target A configuration:
  | Field | Value |
  | cls | Pos |
  | min_ct | 42 |
  | max_ct | 45 |
And: Target B configuration:
  | Field | Value |
  | cls | Any |
And: A well with observations:
  | Observation | Role | Target | CLS | CT |
  | 1 | PEC | Target A | Pos | 44 |
  | 2 | - | Target B | Neg | null |
When: The Combined Outcome Control rule evaluates the well
Then: The well error_code shall be set to "Error A"
And: The well LIMS status shall be null
And: The Run Target for Target A shall have error set to "Error B"

Test: Classification/Discrepancy Result Matching

Given: Combined Outcome configuration with:
  | Field | Value |
  | error_code | Error A |
And: Target configurations:
  | Target | Result |
  | Target A | Any |
  | Target B | Classification/Discrepancy |
  | Target C | Any |
And: A well with observations:
  | Observation | Target | Final CLS | Problems |
  | 1 | Target A | Pos | (none) |
  | 2 | Target B | Amb | CLASSIFICATION |
  | 3 | Target C | Pos | (none) |
When: The Combined Outcome Control rule evaluates the well
Then: The well shall match the combined outcome
And: The well shall receive Error A
And: Target A shall match because result=Any matches Pos
And: Target B shall match because result=Classification/Discrepancy matches observation with CLASSIFICATION problem
And: Target C shall match because result=Any matches Pos

---

Related Design Documents

Design Document	Relevant Sections
SDD Algorithms	Combined Outcomes Algorithm
Combined Outcomes Rule	Base combined outcome matching

---

Appendix: Process Artifacts

Completion Checklist

• All requirements are capability-level (describe behavior, not UI)
• Requirement variants consolidated (no requirement explosion)
• UI details are fully demoted to Illustrative 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 Required

This domain contains a single requirement (REQ-RULES-COMBOUTCTRL-001) that represents a unified capability covering:

• Role verification logic
• Error outcome assignment
• Classification/discrepancy status matching
• CT and quantity range conditions

Rationale: The source document already presents this as a single cohesive rule with multiple matching criteria. No consolidation was necessary as the original structure appropriately captures the capability at the right level of abstraction.

Reversibility: Source requirements preserved 1:1.

• Source: output/pilot/rules/rule-combined-outcomes-control/rule-combined-outcomes-control-restructured.md