CONTROL_FAIL Rule
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: Run-level quality control validation by propagating control well failures to patient wells Domain: RULES-CONTROLFAIL Precedence: Run-level QC enforcement
Statement
The system shall propagate control well failures to patient wells, ensuring that runs with failed quality controls cannot produce valid patient results.
The rule monitors control wells in a run and marks all patient wells with an error code when any control well (with a known mix) has failed. Wells with unknown mixes are excluded from failure counting to prevent false positives from unidentifiable configurations. This enforces the principle that any control failure invalidates the entire run.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-CONTROLFAIL-001 | Mark patient wells with QC error when control wells fail | HIGH | Draft |
| REQ-RULES-CONTROLFAIL-002 | Exclude unknown-mix wells from control failure counting | HIGH | Draft |
Key Integration Points: Well Classification, Mix Configuration, Error Code Registry, Run Management
Rule Summary
| Property | Value |
|---|---|
| Name | CONTROL_FAIL |
| Triggers | When control wells in a run have failures |
| Output | Sets QC error code on patient wells |
| Exclusions | Wells with unknown mixes do not count as failures |
Rule Flowchart (Illustrative)
This diagram illustrates the core control failure detection and propagation logic. The rule evaluates all control wells, excludes unknown-mix wells from failure counting, and marks all patient wells when any known-mix control has failed.
Definitions
| Term | Definition |
|---|---|
| Control Well | A well designated for quality control purposes, not containing patient samples |
| Patient Well | A well containing a patient sample for analysis |
| Unknown Mix | A mix configuration that cannot be identified or matched to known mix definitions |
| QC Error | An error code indicating quality control failure requiring repeat testing |
| Run | A collection of wells processed together on a single plate |
Assumptions
- Control wells are properly identified and mapped in the system configuration
- Mix configuration is available for each well to determine known vs unknown status
- The CONTROL_FAIL rule is properly mapped to execute against control wells
- Error code registry contains the QC error code referenced by this rule
Requirements
Run-Level Quality Control (REQ-RULES-CONTROLFAIL-001)
FR-CONTROLFAIL-001: Mark Patient Wells on Control Failure
The system shall mark patient wells with an error code when one or more control wells have failed in the run.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | Control well statuses | Run wells |
| Input | Control well mix types | Mix configuration |
| Output | QC error code | Patient well records |
Acceptance Criteria
Core Failure Detection:
- Given a run with at least one control well that has failed, when the CONTROL_FAIL rule analyzes a patient well, then the system shall mark the patient well with an error status
- The rule shall evaluate all control wells in the run to determine failure status
- A single control well failure shall be sufficient to trigger patient well errors
- All patient wells in the affected run shall receive the error status
Error Code Assignment:
- The error shall be expressed as an error code (not a text message)
- The error code shall indicate that the well should be repeated due to QC error
Error Handling
- No control wells in run: pass without marking any wells (no control failure to detect)
- All control wells passed: pass without marking patient wells with errors
Trace: Source: 3.0.0-CONTROL_FAIL rule / Context (Lines 17-22), Requirements Table (Row 1) | Jira: BT-2398 | Epic: BT-674 | Tests: See scenarios
Unknown Mix Exclusion (REQ-RULES-CONTROLFAIL-002)
FR-CONTROLFAIL-002: Exclude Unknown Mix Wells from Control Failure Counting
The system shall exclude wells with unknown mixes from control failure counting when evaluating run-level control status.
Acceptance Criteria
Exclusion Logic:
- Given a run with wells that have unknown mixes, when the CONTROL_FAIL rule counts control failures, then wells with unknown mixes shall not be included in the failure count
- Only the "unknown mix" status shall exempt a well from failure counting
- The exclusion shall apply specifically to the failure determination logic
Known-Mix Handling:
- Wells with known, valid mixes that fail shall be counted as failures
Combined Scenarios:
- Given a run where the only failed control wells have unknown mixes, the patient wells shall not be marked with QC errors
- Given a run with both unknown-mix failures and known-mix failures, the known-mix failures shall trigger patient well errors
Assumptions
- Mix status (known vs unknown) is determinable for each well before rule execution
Trace: Source: 3.0.0-CONTROL_FAIL rule / Requirements Table (Row 2) | Jira: BT-2398 | Epic: BT-674 | Tests: See scenarios
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
control_well_mapping | per-kit | Configuration identifying which wells are control vs patient wells | REQ-RULES-CONTROLFAIL-001 |
qc_error_code | INHERITED_CONTROL_FAILURE | Error code assigned to patient wells when control failures exist | REQ-RULES-CONTROLFAIL-001 |
UI Notes (Illustrative)
No UI specifications in source material. This rule operates at the analytics/business logic level without direct UI presentation.
Implementation (Illustrative)
| Component | Location |
|---|---|
| Rule Class | Analyzer/Rules/ControlFailRule.php |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-CONTROLFAIL-001 | Mark Patient Wells on Control Failure | Test | ControlFailRule | See tests | Draft |
| REQ-RULES-CONTROLFAIL-002 | Exclude Unknown Mix Wells from Control Failure Counting | Test | ControlFailRule | See tests | Draft |
Notes
- Original error message text from source: "Well should be repeated due to at least one qc error"
- Per developer note (aron): Error should be implemented as an error code rather than message text
- The exact error code identifier should be defined in the error code registry
- The rule implements the principle that if any control fails on a plate, the entire run should be considered failed
Acceptance Tests
Test: REQ-RULES-CONTROLFAIL-001
Test: Basic Control Failure Detection
Given: Run R1 with Control Well C1 (status = FAILED, mix = known) and Patient Well P1
When: CONTROL_FAIL rule analyzes P1
Then: P1 shall be marked with QC error code
Test: No Control Failures
Given: Run R1 with Control Well C1 (status = PASSED, mix = known) and Patient Well P1
When: CONTROL_FAIL rule analyzes P1
Then: P1 shall not be marked with any error
Test: REQ-RULES-CONTROLFAIL-002
Test: Unknown Mix Exclusion
Given: Run R1 with Control Well C1 (status = FAILED, mix = unknown), Control Well C2 (status = PASSED, mix = known), and Patient Well P1
When: CONTROL_FAIL rule analyzes P1
Then: P1 shall not be marked with error
And: C1 shall be excluded from failure count due to unknown mix
Test: Mixed Scenario - Unknown Mix with Real Failure
Given: Run R1 with Control Well C1 (status = FAILED, mix = unknown), Control Well C2 (status = FAILED, mix = known), and Patient Well P1
When: CONTROL_FAIL rule analyzes P1
Then: P1 shall be marked with QC error code
And: C2 failure shall be counted despite C1 being excluded
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | Control Failure Rule Algorithm |
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
The source contained 2 requirements representing distinct capabilities:
| Original Item | Source Reference | Disposition |
|---|---|---|
| REQ-RULES-CONTROLFAIL-001 | Requirements Table Row 1 | Preserved as-is - core failure detection capability |
| REQ-RULES-CONTROLFAIL-002 | Requirements Table Row 2 | Preserved as-is - distinct exclusion logic capability |
Rationale: These requirements represent separate, independently testable behaviors. REQ-001 defines the core control failure detection and patient well marking. REQ-002 defines specific exclusion logic for unknown mixes. Per RULES domain guidance, these were not consolidated to preserve analytics precision.
Reversibility: Source requirements preserved 1:1.
- Source:
output/pilot/rules/rule-control-fail/rule-control-fail-restructured.md