RWAC Rule - Resolution Well Affecting Control
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: RWAC rule for propagating control well resolution outcomes to patient wells Domain: RULES-RWAC Precedence: After control well resolution assignment
Statement
The system shall propagate resolution outcomes from control wells to their associated patient wells in the same mix.
When a control well is resolved with a resolution code that specifies LIMS status changes, the RWAC rule identifies associated patient wells and applies the resolution's LIMS status based on configured affected statuses. The rule supports fallback controls for backup mix scenarios, resolution priority when multiple controls are resolved, and optional error well inclusion.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-RWAC-001 | Apply resolution code LIMS status to associated patient wells | HIGH | Draft |
| REQ-RULES-RWAC-002 | Use fallback controls when primary controls unavailable | HIGH | Draft |
| REQ-RULES-RWAC-003 | Apply highest priority resolution when multiple controls resolved | HIGH | Draft |
| REQ-RULES-RWAC-004 | Allow error wells to receive resolution outcomes | MEDIUM | Draft |
Key Integration Points: Control well resolution management, Kit Configuration (control label mapping, fallback controls, role priorities), Analytics Engine, LIMS Export
Rule Summary
| Property | Value |
|---|---|
| Name | RWAC |
| Triggers | When control well is resolved with resolution code |
| Output | Sets LIMS status on associated patient wells |
Rule Flowchart (Illustrative)
This diagram illustrates the RWAC decision logic. Specific error well handling and configuration details are specified in the requirements below.
Definitions
| Term | Definition |
|---|---|
| RWAC | Resolution Well Affecting Control - rule that modifies patient well outcomes based on control well resolutions |
| Resolution Code | A code assigned to a control well that determines the outcome for associated patient wells |
| Affected LIMS Status | The set of LIMS statuses that a resolution code can modify |
| Fallback Control | A backup control used when the primary control is unavailable; defined via control label mapping backup mixes |
| Resolution Priority | A numeric value assigned to control roles determining precedence when multiple resolutions apply; lower number indicates higher priority |
| Associated Control | A control well sharing extraction details, targets, and mix with a patient well |
Assumptions
- Control wells have been processed and may have resolution codes assigned before RWAC rule execution
- Resolution codes are configured with affected LIMS statuses and target LIMS status values
- Kit configuration defines control label mappings including backup mixes where applicable
- Role resolution priorities are configured in kit configuration when multiple control types exist
Requirements
Resolution Application (REQ-RULES-RWAC-001)
FR-RWAC-001: Apply Resolution Code LIMS Status to Patient Wells
The system shall apply resolution code LIMS status to associated patient wells when a control well is resolved with a resolution code that specifies LIMS status changes.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | Control well with resolution code | Control resolution |
| Input | Resolution code configuration (affected_lims_statuses, lims_status) | Kit configuration |
| Output | Updated LIMS status | Patient well record |
Acceptance Criteria
Status Matching:
- When resolution affected_lims_statuses do not match patient well current LIMS status, the patient well LIMS status shall remain unchanged
- When resolution affected_lims_statuses match patient well current LIMS status, the patient well LIMS status shall be set to the resolution's lims_status value
All Wells Mode:
- When resolution affected_lims_statuses is set to "All Wells", all associated patient wells shall receive the resolution's LIMS status regardless of current status
- When resolution affected_lims_statuses is "All Wells" and patient well has error_code, the patient well LIMS status shall be set to the resolution's lims_status value
Null Status Handling:
- When resolution lims_status is null and patient well matches, the patient well LIMS status shall be set to null
Trace: Source: 3.0.0-RWAC Rule (Rows 1-2) | Jira: BT-674, BT-3300 | Tests: See scenarios | Related: REQ-RULES-RWAC-004 (error well handling)
Fallback Control Handling (REQ-RULES-RWAC-002)
FR-RWAC-002: Use Fallback Controls When Primary Controls Unavailable
The system shall use fallback controls to determine affected LIMS status when a patient well does not have associated controls from its original mix.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | Control label mapping with backup_mixes | Kit configuration |
| Input | Patient well mix assignment | Run data |
| Output | Resolution application from fallback control | Patient well record |
Acceptance Criteria
Fallback Application:
- Patient wells on a backup mix with no original mix controls present shall receive outcome updates from fallback control resolutions
- Patient wells on a backup mix with original mix control present shall not receive fallback control outcomes (original mix takes precedence)
- Patient wells on a mix not listed as a backup mix shall not receive fallback control outcomes
Configuration:
- Fallback controls shall be defined in kit configuration via control label mapping backup_mixes field
Error Handling
- No associated controls found (primary or fallback): skip RWAC processing and leave patient well unchanged
Trace: Source: 3.0.0-RWAC Rule - Consider Fallback Controls (Rows 1-2) | Jira: BT-4461 | Tests: See scenarios
Resolution Priority (REQ-RULES-RWAC-003)
FR-RWAC-003: Apply Highest Priority Resolution When Multiple Controls Resolved
The system shall apply the resolution from the highest priority control when multiple resolved controls are associated with a patient well.
Acceptance Criteria
Priority Selection:
- When multiple resolved associated controls have different role resolution priorities, the patient well shall receive LIMS status from the control with lowest priority number (highest priority)
- Priority is determined by role's configured resolution_priority value where lower numbers indicate higher precedence
Assumptions
- Role resolution priorities are configured in kit configuration
- Priority values are positive integers with 1 being highest priority
Trace: Source: 3.0.0-Consider Highest Priority Resolved Associated Control (Row 1) | Jira: BT-4900 | Epic: BT-4899 | Tests: See scenarios
Error Well Handling (REQ-RULES-RWAC-004)
FR-RWAC-004: Allow Error Wells to Receive Resolution Outcomes
The system shall allow patient wells with error outcomes to receive new outcomes from control resolutions when the error outcome is explicitly listed in the resolution's affected outcomes configuration.
Acceptance Criteria
Error Outcome Inclusion:
- When patient well error outcome is listed in resolution affected_outcomes, the patient well outcome shall be set to resolution's outcome value
- When patient well error outcome is not listed in resolution affected_outcomes, the patient well outcome shall remain unchanged
Trace: Source: 3.0.0-Allow Error Wells to Get Affected by Control Resolutions (Row 1) | Jira: BT-5268 | Epic: BT-5269 | Tests: See scenarios | Related: REQ-RULES-RWAC-001 (base RWAC rule)
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
resolution_priority | Per role | Numeric priority value for resolution precedence (lower = higher priority) | REQ-RULES-RWAC-003 |
affected_lims_statuses | Per resolution | List of LIMS statuses affected by resolution, or "All Wells" | REQ-RULES-RWAC-001 |
backup_mixes | Per control label mapping | List of mixes that can use this control as fallback | REQ-RULES-RWAC-002 |
affected_outcomes | Per resolution | List of outcomes (including errors) that resolution can modify | REQ-RULES-RWAC-004 |
Open Questions
| ID | Question | Source | Owner | Date Raised |
|---|---|---|---|---|
| OQ-001 | No UI specifications found in source material. RWAC rule is backend analytics processing without direct UI representation. Verify if any UI for resolution management or RWAC results display should be documented. | UI Detail | @tbd | 2026-01-23 |
Notes
- Example use case: A negative well becoming RPT (Repeat) after setting "repeat all negative samples" as a failed control resolution
- The RWAC rule processes wells through a decision tree: Is Associated Control? -> Has Resolution Code? -> Resolution Affects All Wells or Specific LIMS Status Match? -> Apply Resolution
- Fallback controls enable sample wells to be affected by control resolutions even when their original mix control is not present
- Resolution priority ensures deterministic behavior when multiple control types have resolutions that could apply to the same patient well
Implementation (Illustrative)
| Component | Location |
|---|---|
| Rule Class | Analyzer/Rules/RwacRule.php |
| Mix Comparator | Analyzer/WellMixComparator.php |
| LIMS Status Setter | Analyzer/Rules/Concerns/SetLimsStatusToWell.php |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-RWAC-001 | Apply Resolution Code LIMS Status | Test | RwacRule.handle(), RwacRule.getAssociateResolutionCode() | See tests | Draft |
| REQ-RULES-RWAC-002 | Use Fallback Controls | Test | RwacRule.getAssociateResolvedWellForMixWell() | See tests | Draft |
| REQ-RULES-RWAC-003 | Apply Highest Priority Resolution | Test | RwacRule.getAssociateResolvedWells(), sortByRoleResolutionPriority() | See tests | Draft |
| REQ-RULES-RWAC-004 | Allow Error Wells | Test | RwacRule.handle(), ResolutionCode.doesAffectsLimsStatus() | See tests | Draft |
Acceptance Tests
Test: REQ-RULES-RWAC-001
Test: Base Rule - No Match
Given: An Error Resolution with code "Resolution A", affected_lims_statuses "Lims B", and lims_status "Lims A"
And: A Control Well with resolution_code "Resolution A"
And: A Patient Well with lims_status null
When: The Patient well is analyzed through RwacRule
Then: The Patient Well lims_status shall remain null
Test: Base Rule - Match with Status
Given: An Error Resolution with code "Resolution A", affected_lims_statuses "Lims B", and lims_status "Lims A"
And: A Control Well with resolution_code "Resolution A"
And: A Patient Well with lims_status "Lims B"
When: The Patient well is analyzed through RwacRule
Then: The Patient Well lims_status shall be set to "Lims A"
Test: Base Rule - Match with Null Resolution Status
Given: An Error Resolution with code "Resolution A", affected_lims_statuses "Lims B", and lims_status null
And: A Control Well with resolution_code "Resolution A"
And: A Patient Well with lims_status "Lims B"
When: The Patient well is analyzed through RwacRule
Then: The Patient Well lims_status shall be set to null
Test: All Wells Mode - Status Replacement
Given: An Error Resolution with code "Resolution A", affected_lims_statuses "All Wells", and lims_status "Lims A"
And: A Control Well with resolution_code "Resolution A"
And: A Patient Well with lims_status "Lims B"
When: The Patient well is analyzed through RwacRule
Then: The Patient Well lims_status shall be set to "Lims A"
Test: All Wells Mode - With Error Code
Given: An Error Resolution with code "Resolution A", affected_lims_statuses "All Wells", and lims_status "Lims A"
And: A Control Well with resolution_code "Resolution A"
And: A Patient Well with error_code "Error B" and lims_status null
When: The Patient well is analyzed through RwacRule
Then: The Patient Well lims_status shall be set to "Lims A"
Test: REQ-RULES-RWAC-002
Test: Fallback Control Application
Given: A control label mapping with role "Role A", mix "Mix A", and backup mixes "Mix B"
And: A resolution with code "RESOLUTION A", error "ERROR A", other wells affected "All", and affected well outcome "LIMS A"
And: A run with wells:
- Well A1: role Patient, mix "Mix B", outcome "outcome A"
- Well A2: role Patient, mix "Mix C", outcome "outcome A"
- Well A3: role "Role A", mix "Mix A", error "ERROR A"
When: Well A3 is resolved with RESOLUTION A
Then: Well A1 outcome shall be "LIMS A" (backup mix match)
And: Well A2 outcome shall remain "outcome A" (no mix match)
Test: Original Mix Control Present - No Fallback
Given: Control label mapping A with role "Role A", mix "Mix A", backup mixes "Mix B"
And: Control label mapping B with role "Role B", mix "Mix B"
And: A resolution with code "RESOLUTION A", error "ERROR A", other wells affected "All", and affected well outcome "LIMS A"
And: A run with wells:
- Well A1: role Patient, mix "Mix B", outcome "outcome A"
- Well A2: role "Role B", mix "Mix B", outcome "outcome A"
- Well A3: role "Role A", mix "Mix A", error "ERROR A"
When: Well A3 is resolved with RESOLUTION A
Then: Well A1 outcome shall remain "outcome A" (original mix control A2 exists)
Test: Original Mix Control Absent - Fallback Used
Given: Control label mapping A with role "Role A", mix "Mix A", backup mixes "Mix B"
And: A resolution with code "RESOLUTION A", error "ERROR A", other wells affected "All", and affected well outcome "LIMS A"
And: A run with wells:
- Well A1: role Patient, mix "Mix B", outcome "outcome A"
- Well A3: role "Role A", mix "Mix A", error "ERROR A"
When: Well A3 is resolved with RESOLUTION A
Then: Well A1 outcome shall be "LIMS A" (no original mix control, fallback used)
Test: REQ-RULES-RWAC-003
Test: Priority-Based Resolution Selection
Given: Roles configured as:
- Role A with resolution priority 2
- Role B with resolution priority 1
And: Resolutions configured as:
- Resolution A: affects "Lims A", sets lims "Lims B"
- Resolution B: affects "Lims A", sets lims "Lims C"
And: Wells:
- Well A1: role Sample, lims "Lims A"
- Well A2: role "Role A"
- Well A3: role "Role B"
When: Resolutions are applied:
- Well A2 receives Resolution A
- Well A3 receives Resolution B
Then: Well A1 lims shall be set to "Lims C" (from Role B with priority 1)
Test: REQ-RULES-RWAC-004
Test: Error Well Outcome Replacement
Given: A patient well with outcome "Error A"
And: A control well with a resolution that:
- Has affected outcomes including "Error A"
- Sets outcome to "Outcome B"
When: The patient well is executed for RWAC
Then: The patient well outcome shall be set to "Outcome B"
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | RWAC 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 folded into acceptance criteria
- Traceability matrix is complete
Reviewer Notes
No Consolidation Required
All four requirements in the source represent distinct system capabilities:
| Requirement | Capability | Rationale for Preservation |
|---|---|---|
| REQ-RULES-RWAC-001 | Base RWAC rule application | Core capability - applies resolution LIMS status to patient wells |
| REQ-RULES-RWAC-002 | Fallback control handling | Distinct mechanism - handles backup mix scenarios |
| REQ-RULES-RWAC-003 | Resolution priority | Distinct mechanism - handles multiple control resolution conflicts |
| REQ-RULES-RWAC-004 | Error well handling | Extension capability - extends base rule to error outcomes |
Rationale: Per RULES domain guidance, conservative consolidation was applied. Each requirement represents a distinct analytics capability with specific test scenarios. The Given/When/Then acceptance criteria were preserved as detailed ACs to maintain test precision.
Reversibility: Source requirements preserved 1:1.
- Source:
output/srs/rules/rule-rwac.md - Original restructured:
output/pilot/rules/rule-rwac/rule-rwac-restructured.md