WCAF Rule (Multiple Control Failures)
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: WCAF rule for detecting multiple control well failures in a run Domain: RULES-WCAF Precedence: Run-level QC rule (complements CONTROL_FAIL)
Statement
The system shall detect when two or more control wells have failed in a run, marking affected wells for replating with an error message.
The WCAF rule implements run-level quality control by counting control failures across the entire run. Unlike the CONTROL_FAIL rule which triggers on any single failure, WCAF requires a threshold of 2+ failures before triggering. Wells with unknown mixes are excluded from the failure count to prevent configuration issues from falsely triggering run-level failures. When errors are resolved and the count drops below threshold, WCAF errors are automatically cleared.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-WCAF-001 | Detect and mark multiple control failures (2+ threshold) | HIGH | Draft |
| REQ-RULES-WCAF-002 | Exclude unknown mix wells from failure counting | HIGH | Draft |
| REQ-RULES-WCAF-003 | Clear error when resolved failures reduce count below threshold | HIGH | Draft |
Key Integration Points: Control Well Management, Mix Configuration, Error Resolution System, CONTROL_FAIL Rule
Rule Summary
| Property | Value |
|---|---|
| Name | WCAF |
| Threshold | 2+ control failures |
| Triggers | Run-level when multiple controls fail |
| Output | Error: "Well should be replated due to multiple qc errors" |
Rule Flowchart (Illustrative)
This diagram illustrates the core detection, exclusion, and clearing logic. Original control errors are distinct from WCAF-generated errors.
Definitions
| Term | Definition |
|---|---|
| Control Well | A well designated for quality control purposes in a run |
| Control Failure | A control well that has failed its quality control validation |
| Unknown Mix | A well whose mix configuration cannot be identified or matched |
| WCAF Error | The error message generated by this rule when 2+ control failures are detected |
| Countable Failure | A control failure from a well with a known mix (excludes unknown mix wells) |
Assumptions
- Control wells are identifiable within a run via well mapping configuration
- Mix status (known vs unknown) is determinable for each well
- The system can distinguish between original control errors and WCAF-generated errors
- Error resolution events trigger rule re-evaluation
- Users have appropriate permissions to resolve control errors
Requirements
Multiple Control Failure Detection (REQ-RULES-WCAF-001)
FR-WCAF-001: Detect and Mark Multiple Control Failures
The system shall mark wells with an error when two or more control failures exist in the run.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | Control well statuses (passed/failed) | Run data |
| Input | Mix status (known/unknown) | Well configuration |
| Output | Error status on affected wells | Well records |
| Output | Error message | Well display |
Acceptance Criteria
Threshold and Counting:
- Given a run with 2 or more control wells that have failed, when the WCAF rule analyzes the wells, then the system shall mark wells with an error status
- The rule shall count all control failures in the run to determine if the threshold is met
- The threshold for triggering shall be exactly 2 or more control failures
- A run with only 1 control failure shall NOT trigger this rule
Error Message and Scope:
- The error message shall indicate: "Well should be replated due to multiple qc errors"
- The rule shall operate at run level, examining all control wells in the run
- Affected patient samples shall fail by association when controls are marked as error
- The rule shall be mapped to control wells for evaluation
Error Handling
- Unable to determine control well status: log a warning and skip the well in failure counting
- No control wells in run: do not trigger WCAF (0 failures < 2 threshold)
Trace: Source: 3.0.0-Multiple control failures rule (WCAF) / Context (Lines 26-31), Requirements Table (Row 1) | Jira: BT-635 | Tests: BT-675, BT-2345 | Epic: BT-674
Unknown Mix Exclusion (REQ-RULES-WCAF-002)
FR-WCAF-002: Exclude Unknown Mix Wells from Failure Counting
The system shall exclude wells with unknown mixes from multiple failure counting when determining whether the 2+ threshold is met.
Acceptance Criteria
Exclusion Logic:
- Given a run with wells that have unknown mixes, when the WCAF rule counts control failures toward the 2+ threshold, then wells with unknown mixes shall not be included in the failure count
- Given a run with 1 known control failure and 1 unknown mix well failure, when the WCAF rule evaluates the threshold, then the rule shall NOT trigger (only 1 countable failure)
Counting Rules:
- Wells with known, valid mixes that fail shall be counted as failures
- Only the "unknown mix" status shall exempt a well from failure counting
- This exclusion shall apply specifically to the multiple failures determination
Consistency:
- The same exclusion logic shall be applied in the CONTROL_FAIL rule for consistency
- The exclusion shall prevent configuration issues (unknown mixes) from falsely triggering run-level failures
Trace: Source: 3.0.0-Multiple control failures rule (WCAF) / Requirements Table (Row 2) | Jira: BT-635 | Tests: BT-675 | Epic: BT-674
Error Clearing on Resolution (REQ-RULES-WCAF-003)
FR-WCAF-003: Clear Error When Failures Reduce Below Threshold
The system shall clear the multiple control failure error when resolved failures reduce the count below the threshold of 2.
Acceptance Criteria
Re-evaluation Trigger:
- Given a run with 3 control wells where 2 have failed (triggering WCAF), when a user resolves one of the failed control errors, then the multiple control failure error shall be cleared from affected wells
- Re-evaluation shall occur when any control error is resolved
Clearing Logic:
- Given a run where WCAF has triggered and marked wells with error, when errors are resolved leaving only 1 control failure, then the WCAF error message shall be removed
- The threshold re-evaluation logic shall be: if countable failures < 2, clear WCAF error
- The remaining control with its original error may retain that error; only the WCAF-generated error is cleared
Error Distinction:
- The WCAF rule error itself shall NOT be counted as a control failure during re-evaluation
- The rule shall distinguish between original control errors and WCAF-generated errors for re-evaluation
- Partially salvageable runs shall be recoverable through error resolution
Trace: Source: 3.0.0-Multiple control failures rule (WCAF) / Requirements Table (Row 3) | Jira: BT-635 | Tests: BT-2386 | Epic: BT-674
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
wcaf_failure_threshold | 2 | Number of control failures required to trigger the WCAF rule | REQ-RULES-WCAF-001 |
wcaf_error_message | "Well should be replated due to multiple qc errors" | Error message displayed when WCAF triggers | REQ-RULES-WCAF-001 |
[REVIEW REQUIRED: Configuration options inferred from requirements. Verify if these are actually configurable or hardcoded.]
Notes
- This rule is distinct from CONTROL_FAIL which triggers on any single control failure
- Both WCAF and CONTROL_FAIL share the same unknown mix exclusion logic but differ in threshold requirements
- CONTROL_FAIL may still trigger on a single failure even when WCAF does not trigger
- The rule name "WCAF" represents the internal rule identifier in the system
- Source documentation also refers to this as "Multi-control fail"
Rule Comparison: WCAF vs CONTROL_FAIL
| Aspect | CONTROL_FAIL | WCAF |
|---|---|---|
| Threshold | 1+ failures | 2+ failures |
| Trigger | Any single control failure | Multiple control failures only |
| Unknown Mix Exclusion | Yes | Yes |
Implementation (Illustrative)
| Component | Location |
|---|---|
| Rule Class | Analyzer/Rules/WcafRule |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-WCAF-001 | Detect and Mark Multiple Control Failures | Test | WcafRule | BT-675, BT-2345 | Draft |
| REQ-RULES-WCAF-002 | Exclude Unknown Mix Wells from Failure Counting | Test | WcafRule | BT-675 | Draft |
| REQ-RULES-WCAF-003 | Clear Error When Failures Reduce Below Threshold | Test | WcafRule | BT-2386 | Draft |
Acceptance Tests
Test: REQ-RULES-WCAF-001
Test: Basic Multiple Control Failure Detection (2 failures)
Given: Run R1 with:
- Control Well C1 (status = FAILED, mix = known)
- Control Well C2 (status = FAILED, mix = known)
- Control Well C3 (status = PASSED, mix = known)
- Patient Well P1
When: WCAF rule analyzes the run
Then: Wells shall be marked with error: "Well should be replated due to multiple qc errors"
And: 2 failures >= threshold of 2
Test: Single Control Failure (No Trigger)
Given: Run R1 with:
- Control Well C1 (status = FAILED, mix = known)
- Control Well C2 (status = PASSED, mix = known)
- Patient Well P1
When: WCAF rule analyzes the run
Then: No WCAF error shall be applied
And: 1 failure < threshold of 2
Test: REQ-RULES-WCAF-002
Test: Unknown Mix Exclusion
Given: Run R1 with:
- Control Well C1 (status = FAILED, mix = unknown)
- Control Well C2 (status = FAILED, mix = known)
- Patient Well P1
When: WCAF rule analyzes the run
Then: No WCAF error shall be applied
And: Only 1 countable failure (C1 excluded due to unknown mix)
Test: Unknown Mix with Two Real Failures
Given: Run R1 with:
- Control Well C1 (status = FAILED, mix = unknown)
- Control Well C2 (status = FAILED, mix = known)
- Control Well C3 (status = FAILED, mix = known)
- Patient Well P1
When: WCAF rule analyzes the run
Then: Wells shall be marked with WCAF error
And: 2 countable failures (C2 and C3, C1 excluded)
Test: REQ-RULES-WCAF-003
Test: Error Clearing After Resolution
Given: Run R1 with:
- Control Well C1 (status = FAILED, mix = known)
- Control Well C2 (status = FAILED, mix = known)
- Control Well C3 (status = FAILED, mix = known)
- WCAF error currently applied (3 failures)
When: User resolves C1 error
Then: WCAF error shall be maintained (2 failures remain)
When: User resolves C2 error
Then: WCAF error shall be cleared (1 failure remains < 2)
And: C3 may still show its original error
Test: WCAF Error Not Counted as Control Failure
Given: Run R1 with:
- Control Well C1 (status = FAILED, mix = known)
- Control Well C2 (status = FAILED, mix = known)
- WCAF error applied to wells
When: User resolves C1 error
Then: Re-evaluation shall count only C2's original failure (count = 1)
And: WCAF error shall NOT be counted toward the threshold
And: WCAF error shall be cleared (1 < 2)
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | Control Failure Detection |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion) - N/A, distinct capabilities
- 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, none identified
- 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 Required
The three requirements in this domain represent distinct, non-overlapping capabilities:
| Requirement | Capability | Rationale for Preservation |
|---|---|---|
| REQ-RULES-WCAF-001 | Detection and marking | Core rule trigger logic |
| REQ-RULES-WCAF-002 | Exclusion filtering | Distinct filtering behavior affecting threshold calculation |
| REQ-RULES-WCAF-003 | Dynamic clearing | Distinct re-evaluation behavior on user action |
Rationale: These requirements cannot be consolidated without losing critical testable behaviors. Each represents a distinct system capability that must be independently verifiable for analytics rule validation.
Reversibility: Source requirements preserved 1:1.
- Source:
output/pilot/rules/rule-wcaf/rule-wcaf-restructured.md