THRESHOLD Rule

Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: Validates runfile threshold values against mix configuration expected thresholds Domain: RULES-THRESH Precedence: Standard rules execution order

---

Statement

The system shall validate that threshold values recorded in runfiles match the expected threshold values specified in mix setup configuration, raising errors when mismatches are detected or when threshold configuration is missing.

Threshold errors are permanent and cannot be resolved through any application workflow, ensuring audit trail integrity. When threshold configuration is absent, a THRESHOLD_MISSED error is applied to indicate the rule cannot execute properly.

---

Quick Reference

ID	Core Behavior	Priority	Status
REQ-RULES-THRESH-001	Validates threshold value matches expected configuration	HIGH	Draft
REQ-RULES-THRESH-002	Persists threshold errors permanently (non-resolvable)	HIGH	Draft
REQ-RULES-THRESH-003	Detects missing threshold configuration	HIGH	Draft

Key Integration Points: Runfile Parser, Kit Configuration / Mix Setup, Analytics Engine, Error Management

Rule Summary

Property	Value
Name	THRESHOLD
Error Codes	THRESHOLD, THRESHOLD_MISSED
Triggers	When evaluating observation threshold values
Output	Sets error codes on observations/wells

---

Rule Flowchart (Illustrative)

This diagram illustrates the threshold validation and error persistence logic. It does not specify UI layout, styling, or interaction details.

---

Definitions

Term	Definition
Threshold	A numeric value used during PCR analysis to determine cycle threshold (CT) values
Runfile Threshold	The actual threshold value recorded in the runfile by the lab technician
Expected Threshold	The configured threshold value specified in the mix setup sheet/table
Observation	A single measurement point within a well, associated with a target and dye
targetThreshold	Configuration field containing the expected threshold for a target

---

Assumptions

• The THRESHOLD rule is executed as part of the standard run analysis workflow
• Mix setup configuration includes an "Expected Threshold" field
• Observations in the runfile contain threshold values
• Rule execution occurs at the per-observation level
• Error persistence ensures audit trail integrity for threshold validation failures

---

Requirements

Threshold Validation (REQ-RULES-THRESH-001)

FR-THRESH-001: Validate Threshold Value

The system shall validate that the threshold value in the runfile matches the expected threshold from the mix configuration for each observation.

Inputs/Outputs

Direction	Data	Source/Target
Input	Runfile threshold value	Runfile Parser
Input	Expected threshold value	Mix Setup Configuration
Output	THRESHOLD error	Observation record

Acceptance Criteria

Matching Logic:

• Given an observation with a threshold value in the runfile and an "Expected Threshold" value defined in the target configuration, when the THRESHOLD rule is executed, then if the runfile threshold does not match the expected threshold, a THRESHOLD error shall be raised on that observation
• The rule shall evaluate each observation in the run independently
• The comparison shall be exact (threshold in runfile must equal expected threshold from target.expected_threshold)
• The rule shall perform comparison at the per-observation level

Configuration:

• The expected threshold value shall be retrieved from the target configuration (target.expected_threshold field)
• The target.expected_threshold is configured via Mix and Targets sheet import or UI (see REQ-KITCFG-001)
• Valid expected_threshold values: 0-1000 for passive targets, 0-100,000,000 for non-passive targets

Rule Identity:

• The rule shall use Rule ID: THRESHOLD
• The rule shall use Error Code: THRESHOLD when mismatch is detected

Error Handling

• Threshold mismatch detected: The system shall raise a THRESHOLD error on the affected observation

Trace: Source: 3.0.0-Threshold rule (Row 1, Row 1 Sub-requirements) | Jira: BT-1384 | Epic: BT-674 | Tests: [See BT-1384 scenarios](#test-req-rules-thresh-001)

---

Error Persistence (REQ-RULES-THRESH-002)

FR-THRESH-002: Persist Threshold Errors

The system shall persist threshold errors on wells and prevent their resolution or removal through any application workflow.

Acceptance Criteria

Error Permanence:

• When a well has a threshold-related error applied, the error shall not be resolvable through the user interface
• The error shall not be removable from the well in any workflow
• Users shall not have an option to resolve threshold errors
• The system shall implement permanent (non-resolvable) error persistence
• The error persistence shall apply to all THRESHOLD-related errors on wells

Re-analysis Behavior:

• Re-analysing the run shall retain the imported threshold and preserve the error
• Re-analysis workflows shall preserve existing threshold errors
• The original threshold value that was imported shall be retained for rule evaluation on re-analysis
• The system shall retain errors during re-analysis

Error Handling

• User attempts to resolve threshold error: The system shall block or reject the resolution attempt
• Re-analysis performed on well with threshold error: The system shall retain the THRESHOLD error

Trace: Source: 3.0.0-Threshold rule (Row 2) | Jira: BT-1616 | Epic: BT-674 | Release: 2.9.3 | Tests: [See BT-1616 scenarios](#test-req-rules-thresh-002)

---

Missing Configuration Detection (REQ-RULES-THRESH-003)

FR-THRESH-003: Detect Missing Threshold Configuration

The system shall set a THRESHOLD_MISSED error when the required threshold configuration is not provided for an observation.

Acceptance Criteria

Detection Logic:

• When a well has an observation with no target threshold configured (targetThreshold = null), and the THRESHOLD rule is executed, then the well shall receive the THRESHOLD_MISSED error code
• The rule shall check for the presence of threshold configuration before validation
• The rule shall trigger when targetThreshold = null (or not defined)

Error Application:

• Missing configuration shall result in THRESHOLD_MISSED error (not rule skip or silent failure)
• The error shall indicate that the rule cannot run due to missing configuration
• The rule shall use Error Code: THRESHOLD_MISSED
• The rule shall apply errors at the well level

Error Handling

• targetThreshold is null or not defined: The system shall apply THRESHOLD_MISSED error to the well

Trace: Source: 3.0.0-THRESHOLD rule - add THRESHOLD_MISSED error (Row 1) | Jira: BT-4154 | Epic: BT-4148 | Tests: [See BT-4167 scenario](#test-req-rules-thresh-003)

---

Configuration Options

Option	Default	Description	Affects
target.expected_threshold	None (required)	Expected threshold value per target configuration. Validated as 0-1000 for passive targets, 0-100M for non-passive targets. Configured via Mix and Targets import or UI (REQ-KITCFG-001).	REQ-RULES-THRESH-001

---

UI Notes (Illustrative)

REQ-RULES-THRESH-001

• JSON testing: Add target_threshold property to observations for testing
• Configuration reference: Quest DELTA config sheet (includes changes for 1:4s and threshold rule)

REQ-RULES-THRESH-002

• Resolution controls should be disabled/hidden for threshold errors
• Re-analysis UI should indicate that threshold errors will be preserved

---

Implementation (Illustrative)

Component	Location
Rule Class	Analyzer/Rules/ThresholdRule

---

Traceability Matrix

Requirement	Title	Verification	Implementation	Test Cases	Status
REQ-RULES-THRESH-001	Validate Threshold Value	Test	ThresholdRule	BT-1384	Draft
REQ-RULES-THRESH-002	Persist Threshold Errors	Test	ThresholdRule	BT-1616	Draft
REQ-RULES-THRESH-003	Detect Missing Threshold Configuration	Test	ThresholdRule	BT-4167	Draft

---

Notes

• Target release for core functionality: 2.9.0
• Error persistence added in release 2.9.3
• THRESHOLD_MISSED error is part of Phase 2A initiative to verify rules have needed configuration data
• Part of broader initiative (BT-4148) to verify rules have needed well/config info to run

---

Acceptance Tests

Test: REQ-RULES-THRESH-001

Back to requirement

Test: Threshold Mismatch Detection

Given:
  Observation with threshold value X in runfile
  Expected threshold value Y in mix setup configuration
  X != Y

When:
  THRESHOLD rule is executed

Then:
  Observation shall have THRESHOLD error

Test: Threshold Match - No Error

Given:
  Observation with threshold value X in runfile
  Expected threshold value X in mix setup configuration

When:
  THRESHOLD rule is executed

Then:
  Observation shall not have THRESHOLD error

---

Test: REQ-RULES-THRESH-002

Back to requirement

Test: Error Non-Resolvable

Given:
  Well with THRESHOLD error applied

When:
  User attempts to resolve the error

Then:
  Resolution shall be blocked
  Error shall remain on well

Test: Error Persists on Re-analysis

Given:
  Well with THRESHOLD error applied
  Original imported threshold value retained

When:
  Run is re-analysed

Then:
  THRESHOLD error shall persist on well
  Original threshold value shall be used for rule evaluation

---

Test: REQ-RULES-THRESH-003

Back to requirement

Test: Missing Threshold Configuration

Given:
  Well with observation
  targetThreshold = null

When:
  Analyze observation on THRESHOLD rule

Then:
  Well has THRESHOLD_MISSED error

---

Related Design Documents

Design Document	Relevant Sections
SDD Algorithms	Rule Execution

---

Appendix: Process Artifacts

Completion Checklist

• All requirements are capability-level (describe behavior, not UI)
• Requirement variants consolidated (no requirement explosion) - N/A: no consolidation needed
• 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 Applied

The three source requirements represent distinct, independently testable capabilities:

Original Item	Source Reference	Disposition
REQ-RULES-THRESH-001 (Threshold validation)	3.0.0-Threshold rule (Row 1)	Retained as REQ-RULES-THRESH-001
REQ-RULES-THRESH-002 (Error persistence)	3.0.0-Threshold rule (Row 2)	Retained as REQ-RULES-THRESH-002
REQ-RULES-THRESH-003 (Missing config detection)	3.0.0-THRESHOLD rule - add THRESHOLD_MISSED error	Retained as REQ-RULES-THRESH-003

Rationale: These requirements represent three distinct system responsibilities:

1. Validating threshold values (core rule logic)
2. Managing error persistence (error lifecycle behavior)
3. Detecting missing configuration (defensive validation)

Conservative consolidation was applied per RULES domain guidance. No consolidation was appropriate as these are distinct capabilities with different triggers, behaviors, and error codes.

Reversibility: Source requirements preserved 1:1.

• Source: output/pilot/rules/rule-threshold/rule-threshold-restructured.md
• Design: output/pilot/rules/rule-threshold/sdd/rule-threshold-design.md