WT Rule (Associated Well Error)
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: Error propagation from failed control wells to associated patient wells Domain: RULES-WT Precedence: After control failure detection rules
Statement
The system shall propagate error messages from failed control wells to all associated patient wells in the same mix, blocking export until the control error is resolved.
When a control fails in a run, all patient samples for the same mix are marked with an error because there might be something wrong with the run. The rule distinguishes between extraction and non-extraction control failures, providing specific error messages for each case. When control errors are resolved, associated patient well errors are automatically cleared. Additionally, when fallback shared control is enabled, patient wells in backup mixes inherit control errors via the backup_mix relationship.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-WT-001 | Propagate control failure errors to patient wells | HIGH | Draft |
| REQ-RULES-WT-002 | Clear patient well errors on control resolution | HIGH | Draft |
| REQ-RULES-WT-003 | Check fallback mixes for control errors | MEDIUM | Draft |
Key Integration Points: Control Failure Detection Rules (upstream), Well Data Store, Export Module, Client Configuration
Rule Summary
| Property | Value |
|---|---|
| Name | WT (Well Transfer) |
| Precedence | After all control failure detection rules |
| Triggers | When control well has failed in a run |
| Output | Sets error message on associated patient wells |
Rule Flowchart (Illustrative)
This diagram illustrates the error propagation and clearing logic. It does not specify UI layout, styling, or interaction details.
Definitions
| Term | Definition |
|---|---|
| WT Rule | Well Transfer rule - the rule identifier for associated well error propagation |
| Control Well | A well containing control samples used for quality validation |
| Patient Well | A well containing patient samples for diagnostic analysis |
| Mix | A reagent configuration that groups wells together |
| Extraction Control | A control that validates the extraction process |
| Non-Extraction Control | A control that validates non-extraction aspects of the run |
| Fallback Mix | A backup mix configuration used when primary controls are unavailable |
| PC | Positive Control role type |
| NC | Negative Control role type |
| Role to Target Mapping | Configuration that maps control roles to targets with primary and backup mix assignments |
Assumptions
- All control failure detection rules have completed execution before the WT rule runs
- A well belongs to exactly one mix
- Client configuration is immutable during rule execution
- Error propagation is transactional - all associated wells are marked or none
- Wells can be identified as control or patient wells
- Wells can be identified as extraction or non-extraction controls
Requirements
Error Propagation (REQ-RULES-WT-001)
FR-WT-001: Propagate Control Failure Errors to Patient Wells
The system shall mark patient wells with an appropriate error message when an associated control well in the same mix has failed.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | Control well failure status | Control failure detection rules |
| Input | Mix association | Well configuration |
| Output | Error message on patient wells | Well data store |
| Output | Export block flag | Export module |
Acceptance Criteria
Error Message Selection:
- Given a run with a non-extraction control that has failed, when the WT rule analyzes patient wells for the same mix, then the system shall mark those patient wells with the error message: "An associated control has failed. That error must be resolved before this well can be exported."
- Given a run with an extraction control that has failed, when the WT rule analyzes patient wells for the same mix, then the system shall mark those patient wells with the error message: "An associated extraction control has failed. That error must be resolved before this well can be exported."
Scope and Blocking:
- The error propagation shall apply to all patient wells sharing the same mix as the failed control
- The error shall prevent the affected wells from being exported until resolved
- The error message text shall explicitly instruct users that the control error must be resolved before export
Rule Execution:
- The rule shall distinguish between extraction and non-extraction control types
- The rule execution shall require all control failure detection rules to complete before the WT rule executes
Error Handling
- Missing mix association: The system shall log a warning and skip processing for that well
- Well update failure: The system shall retry once, then fail run processing with notification
Trace: Source: 3.0.0-WT rule - associated well error / Context (Lines 27-31), Requirements Table (Row 1) | Jira: BT-726 | Epic: BT-674 | Tests: BT-749, BT-750, BT-1523, BT-1557, BT-1558, BT-1559
Error Resolution (REQ-RULES-WT-002)
FR-WT-002: Clear Patient Well Errors on Control Resolution
The system shall automatically clear WT error messages from patient wells when the associated control well error is resolved.
Acceptance Criteria
Automatic Clearing:
- Given patient wells that have WT errors due to a failed control, when the failed control's error is resolved, then the WT error message shall be removed from all associated patient wells
- The error clearing shall be automatic upon control error resolution
- All patient wells associated with the previously failed control shall have their WT errors cleared
Export Eligibility:
- After error clearing, the patient wells shall be eligible for export (assuming no other errors exist)
Trace: Source: 3.0.0-WT rule - associated well error / Requirements Table (Row 2) | Jira: BT-726 | Epic: BT-674 | Tests: BT-1524, BT-1560, BT-1561, BT-1562 | Related: REQ-RULES-WT-001 (inverse behavior)
Fallback Mix Support (REQ-RULES-WT-003)
FR-WT-003: Check Fallback Mixes for Control Errors
The system shall extend error checking to include fallback (backup) mixes when the fallback shared control configuration is enabled.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | Fallback shared control setting | Client configuration |
| Input | Role to target mappings | Kit configuration |
| Output | INHERITED_CONTROL_FAILURE error | Patient well in backup mix |
Acceptance Criteria
Configuration-Dependent Behavior:
- When fallback shared control is disabled, patient wells in backup mixes shall not inherit control errors from primary mix controls
- When fallback shared control is enabled, patient wells in backup mixes shall inherit control errors via the backup_mix relationship
- The error code used for fallback-propagated errors shall be INHERITED_CONTROL_FAILURE
Backup Mix Relationship:
- The backup_mix relationship shall be defined in role-to-target mappings configuration
- The fallback mix checking shall work in conjunction with the mincontrols rule
Error Handling
- Configuration read failure: The system shall use default (fallback disabled) and log error
- Missing role to target mapping: The system shall skip fallback check for that well
Trace: Source: 3.0.0-WT rule - associated well error / Requirements Table (Row 3) | Jira: BT-3883 | Epic: BT-674 | Tests: BT-3940 | Related: REQ-RULES-WT-001, mincontrols rule (BT-3883)
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
fallback_shared_control | false | Enables/disables fallback mix error checking for control failures | REQ-RULES-WT-003 |
UI Notes (Illustrative)
REQ-RULES-WT-001 Display
Error Display:
- Patient wells display error indicator with appropriate message when associated controls fail
- Tooltip displays full error message on hover
- Export attempted with WT error shall be blocked with notification
User Interaction:
- See reference screenshot:
media/image179.png - Error indicators show workflow for error resolution
- Patient wells marked with errors have distinct visual treatment
REQ-RULES-WT-002 Display
Error Resolution Display:
- Error indicator removed from associated patient wells automatically
- No manual intervention required to clear WT errors when control is resolved
Implementation (Illustrative)
| Component | Location |
|---|---|
| Rule Class | Analyzer/Rules/WtRule |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-WT-001 | Propagate Control Failure Errors to Patient Wells | Test | WtRule | BT-749, BT-750, BT-1523, BT-1557, BT-1558, BT-1559 | Draft |
| REQ-RULES-WT-002 | Clear Patient Well Errors on Control Resolution | Test | WtRule | BT-1524, BT-1560, BT-1561, BT-1562 | Draft |
| REQ-RULES-WT-003 | Check Fallback Mixes for Control Errors | Test | WtRule | BT-3940 | Draft |
Notes
- Rule execution dependency: All control failure detection rules must execute before the WT rule
- The automatic error clearing (REQ-RULES-WT-002) implements the inverse behavior of error propagation (REQ-RULES-WT-001), reducing manual effort when control issues are resolved
- Fallback shared control is a client-level configuration setting
- Legacy behavior (pre-fallback feature) only checked primary mix associations
Acceptance Tests
Test: REQ-RULES-WT-001
Test: Non-extraction control failure propagates error
Given: A run with a non-extraction control that has failed
And: Patient wells exist for the same mix
When: The WT rule analyzes patient wells for the same mix
Then: The system shall mark those patient wells with the error message: "An associated control has failed. That error must be resolved before this well can be exported."
Test: Extraction control failure propagates specific error
Given: A run with an extraction control that has failed
And: Patient wells exist for the same mix
When: The WT rule analyzes patient wells for the same mix
Then: The system shall mark those patient wells with the error message: "An associated extraction control has failed. That error must be resolved before this well can be exported."
Test: REQ-RULES-WT-002
Test: Error clearing on control resolution
Given: Patient wells that have WT errors due to a failed control
When: The failed control's error is resolved
Then: The WT error message shall be removed from all associated patient wells
And: The patient wells shall be eligible for export (assuming no other errors exist)
Test: REQ-RULES-WT-003
Test: Fallback shared control disabled
Given: Client configuration: fallback shared control = disabled
And: Error code: INHERITED_CONTROL_FAILURE
And: Roles: role1 (type: PC), role2 (type: NC)
And: Mixes: mix1, mix2
And: Targets: target1 (mix: mix1)
And: Role to target mappings:
- Mapping1: role=role1, target=target1, mix=mix1, backup_mix=mix2
- Mapping2: role=role2, target=target1, mix=mix1, backup_mix=mix2
And: Wells:
- A1: Control, mix1, role=role1, mapping=Mapping1
- A2: Patient, mix2
When: Well A2 executes through WT rule
Then: Well A2 shall not get an error
Test: Fallback shared control enabled
Given: Client configuration: fallback shared control = enabled
And: Error code: INHERITED_CONTROL_FAILURE
And: Roles: role1 (type: PC), role2 (type: NC)
And: Mixes: mix1, mix2
And: Targets: target1 (mix: mix1)
And: Role to target mappings:
- Mapping1: role=role1, target=target1, mix=mix1, backup_mix=mix2
- Mapping2: role=role2, target=target1, mix=mix1, backup_mix=mix2
And: Wells:
- A1: Control, mix1, role=role1, mapping=Mapping1
- A2: Patient, mix2
When: Well A2 executes through WT rule
Then: Well A2 shall get the error: INHERITED_CONTROL_FAILURE
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | WT Rule Algorithm |
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 - N/A, no open questions
- Consolidations documented in Reviewer Notes with reversibility info
- Module can survive a full UI redesign unchanged
- Refinements folded into acceptance criteria
- Traceability matrix is complete
Reviewer Notes
No Consolidation Applied
The three requirements in this domain represent distinct, independently testable capabilities:
| Requirement | Capability | Rationale for Preservation |
|---|---|---|
| REQ-RULES-WT-001 | Error propagation from failed controls | Core analytics behavior - must be precise |
| REQ-RULES-WT-002 | Error clearing on resolution | Inverse behavior with separate test coverage |
| REQ-RULES-WT-003 | Fallback mix checking | Configuration-dependent variant with different error code |
Rationale: Per RULES domain guidance, conservative consolidation is applied. These requirements represent different system behaviors (propagate vs clear vs fallback check), each with separate Jira tickets and test coverage. Aggressive merging would obscure the distinct test scenarios and error handling paths.
Reversibility: Source requirements preserved 1:1.
- Source:
output/pilot/rules/rule-wt/rule-wt-restructured.md