Mixes Missing Rule
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: MISSING_MIXES rule for detecting missing mixes in combined outcome evaluation Domain: RULES-MIXMISS Precedence: After Multi Mix Combined Check
Statement
The system shall identify when wells are missing required mixes for combined outcome evaluation, assign appropriate error codes, and manage re-analysis workflows when missing mixes become available.
The rule evaluates wells during import and analysis, checking for incomplete mix configurations based on combined outcome mappings. When mixes are missing, wells receive the COMBINED_MIXES_WELLS_MISSING error code. Cross-run resolution allows wells from previous runs to satisfy missing mix requirements when enabled.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-MIXMISS-001 | Identifies missing mixes and assigns error codes to affected wells | HIGH | Draft |
| REQ-RULES-MIXMISS-002 | Persists and displays missing mix information in outcome messages | HIGH | Draft |
| REQ-RULES-MIXMISS-003 | Updates run status when missing mixes become available | HIGH | Draft |
| REQ-RULES-MIXMISS-004 | Ensures Multi Mix Combined Check executes before Missing Check | HIGH | Draft |
Key Integration Points: Combined Outcome Rule, Kit Configuration, Run Management, Well Processing Engine
Rule Summary
| Property | Value |
|---|---|
| Name | MISSING_MIXES |
| Error Code | COMBINED_MIXES_WELLS_MISSING |
| Triggers | When combined outcomes have mixes_missing toggle enabled |
| Output | Sets error code on well, updates run re-analysis status |
Rule Flowchart (Illustrative)
This diagram illustrates the missing mixes detection and cross-run resolution logic. Well success criteria and detailed matching logic follow in requirements below.
Definitions
| Term | Definition |
|---|---|
| Mix | A configured combination of targets and dyes for an assay |
| Combined Outcome | An outcome type that evaluates results across multiple mixes |
| Successful Well | A well that meets criteria for mix availability (no errors, has mixes missing error, or has information-typed LIMS) |
| Cross-Run Resolution | The process of using wells from previous runs to satisfy missing mix requirements |
| COMBINED_MIXES_WELLS_MISSING | Error code assigned when required mixes are not present |
Assumptions
- Combined outcomes are configured with required mixes before the rule executes
- The Multi Mix Combined Check executes before the Multi Mix Missing Check
- Users have appropriate permissions to view run status and well outcomes
Requirements
Missing Mixes Detection (REQ-RULES-MIXMISS-001)
FR-MIXMISS-001: Identify Missing Mixes for Combined Outcome Evaluation
The system shall identify when wells are missing required mixes for combined outcome evaluation and assign the COMBINED_MIXES_WELLS_MISSING error code to affected wells.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | Well data (mix, accession, type) | Run import |
| Input | Combined outcome mappings (mixes, toggles) | Kit configuration |
| Input | Historical wells (when cross-run enabled) | History store |
| Output | Error code assignment | Well record |
Acceptance Criteria
Toggle Behavior:
- The rule shall only trigger for combined outcomes that have the mixes_missing toggle enabled (true)
- When mixes_missing is disabled (false), wells shall not receive the missing mixes error from this rule
Mix Presence Determination:
- A mix shall be considered missing only when there are no successful wells for that mix
Successful Well Definition:
- A well shall be considered successful when it has no errors of any type
- A well shall be considered successful when it has the mixes missing error (COMBINED_MIXES_WELLS_MISSING)
- A well shall be considered successful when it has an information-typed LIMS status
- Wells with Label Error, Error, Warning, or Information-typed errors (non-LIMS) shall NOT be considered successful
- Wells with Warning/Exclude-typed LIMS shall NOT be considered successful
Cross-Run Resolution:
- When allow_other_runs_to_be_used is enabled (true), wells from previous runs shall be considered for mix result satisfaction
- When allow_other_runs_to_be_used is disabled (false), only wells from the current run shall be considered
- When using history runs, only wells that have the missing mixes error shall be used to satisfy the missing mix requirement
- Cross-run well eligibility shall require only wells with the COMBINED_MIXES_WELLS_MISSING error code from other runs to be considered for cross-run resolution
- Wells without the COMBINED_MIXES_WELLS_MISSING error code shall not contribute to cross-run mix resolution
Error Handling
- No combined outcomes with mixes_missing enabled: rule does not trigger
- All mixes present: no error assigned to wells
Trace: Source: 3.0.0-Missing Mixes Rule - Multi Mix Missing Check (Rows 1-5) | Jira: BT-4396, BT-4215 | Epic: BT-4051 | Tests: See scenarios
Missing Mixes Information (REQ-RULES-MIXMISS-002)
FR-MIXMISS-002: Track and Display Missing Mixes Information
The system shall persist the specific mixes that are missing for each well and provide visibility into this information through the outcome message.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | List of missing mix names | Missing mixes detection |
| Output | Persisted missing mix list | Well record (database) |
| Output | Populated outcome message | User display |
Acceptance Criteria
Data Persistence:
- The system shall store the list of missing mixes along with the well in the database
Message Display:
- When the error message contains a wildcard placeholder for missing mixes, the system shall populate it with the actual missing mix names
- The outcome message shall contain the names of the missing mixes when displayed to the user
Trace: Source: 3.0.0-Missing Mixes Rule - Multi Mix Missing Check (Row 6) | Jira: BT-4215 | Epic: BT-4051 | Tests: See scenarios
Re-analysis Status (REQ-RULES-MIXMISS-003)
FR-MIXMISS-003: Indicate Re-analysis Readiness for Missing Mixes
The system shall update the run status to indicate re-analysis readiness when previously missing mixes are uploaded in subsequent runs.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | New run wells (mix, accession) | Run import |
| Input | Old runs with missing mixes errors | History store |
| Output | Run status update | Run record |
Acceptance Criteria
Status Update Conditions:
- The run status shall change to "Reanalysis required (Missing mixes uploaded)" when all previously missing mixes for the run are now available (from other runs) AND the run does not have any existing resolution status
- If only some of the missing mixes become available (not all), the run status shall remain unchanged
Precedence Rules:
- If the run already has a resolution status (e.g., "Reanalysis required (Westgard)"), the missing mixes availability shall NOT change the run status
- The existing resolution status shall take precedence over the missing mixes re-analysis status
Error Handling
- Partial mixes available: no status change
- Existing resolution status: preserve existing status
Trace: Source: 3.0.0-Missing Mixes Rule - Multi Mix Missing Check (Rows 7-9) | Epic: BT-4051 | Tests: See scenarios
Rule Execution Ordering (REQ-RULES-MIXMISS-004)
FR-MIXMISS-004: Execute Multi Mix Combined Check Before Missing Check
The system shall execute the Multi Mix Combined Check from the Combined Outcome Rule immediately before the Multi Mix Missing Check.
Acceptance Criteria
Execution Order:
- The Multi Mix Combined Check (from Combined Outcome Rule) shall execute before the Multi Mix Missing Check
- The same combined outcome multi mix check logic shall be reused
Trace: Source: 3.0.0-Missing Mixes Rule - Multi Mix Combined Check (Row 1) | Jira: BT-5159 | Tests: See scenarios | Related: Combined Outcome Rule - Multi Mix Combined Outcomes
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
mixes_missing | false | Enables/disables the Missing Mixes Rule for a combined outcome | REQ-RULES-MIXMISS-001 |
allow_other_runs_to_be_used | false | Enables/disables cross-run mix resolution | REQ-RULES-MIXMISS-001, REQ-RULES-MIXMISS-003 |
Open Questions
| ID | Question | Source | Owner | Date Raised |
|---|---|---|---|---|
| OQ-001 | Confirm error handling behavior when combined outcome configuration is invalid or missing | Error handling | @tbd | 2026-01-23 |
| OQ-002 | Define behavior when I/O failures occur during well processing | Error handling | @tbd | 2026-01-23 |
Notes
- Rule programmatic name:
MISSING_MIXES - Error code:
COMBINED_MIXES_WELLS_MISSING - The mixes missing error is unique in that wells with this error are still considered "successful" for mix availability purposes
- This design allows partial runs to be completed when missing mixes become available in subsequent runs
UI Notes (Illustrative)
FR-MIXMISS-001 UI Specifications
- Configuration path: Kit Configuration -> Combined Outcomes -> Mixes Missing toggle
- Configuration path: Kit Configuration -> Combined Outcomes -> Allow other runs to be used to find matching toggle
FR-MIXMISS-002 UI Specifications
- Message format supports wildcard substitution for dynamic mix names in outcome messages
FR-MIXMISS-003 UI Specifications
- Status message: "Reanalysis required (Missing mixes uploaded)"
- Display location: Run file list -> Run Status column
Implementation (Illustrative)
| Component | Location |
|---|---|
| Rule Class | Analyzer/Rules/MissingMixesRule.php |
| Combined Outcome Satisfier | Analyzer/Rules/Concerns/CombinedOutcomes/SatisfiesCombinedOutcomeForMissingMixes.php |
| Outcome Setter | Analyzer/Rules/Concerns/CombinedOutcomes/SetOutcomeToWell.php |
| Recently Uploaded Wells | Analyzer/RecentlyUploadedWellsGetter.php |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-MIXMISS-001 | Identify Missing Mixes | Test | MissingMixesRule | [Pending] | Draft |
| REQ-RULES-MIXMISS-002 | Track and Display Missing Mixes | Test | MissingMixesRule | [Pending] | Draft |
| REQ-RULES-MIXMISS-003 | Re-analysis Readiness | Test | MissingMixesRule | [Pending] | Draft |
| REQ-RULES-MIXMISS-004 | Execution Ordering | Test | MissingMixesRule | [Pending] | Draft |
Acceptance Tests
Test: REQ-RULES-MIXMISS-001
Test: Well receives error when mixes are missing
Given: outcome mapping with mixes_missing: true
And: mix results configured for Mix A, Mix B, Mix C
And: run contains wells for Mix A and Mix B only
When: well A is analyzed through Missing Mixes rule
Then: well A shall receive the COMBINED_MIXES_WELLS_MISSING error
And: Mix C shall be identified as missing
Test: Well does not receive error when all mixes present
Given: outcome mapping with mixes_missing: true
And: mix results configured for Mix A, Mix B, Mix C
And: run contains wells for Mix A, Mix B, and Mix C
When: well A is analyzed through Missing Mixes rule
Then: well A shall not receive the missing mixes error
Test: Toggle disabled - no error assigned
Given: outcome mapping with mixes_missing: false
And: mix results configured for Mix A, Mix B
And: run contains well for Mix A only
When: run is imported
Then: well A shall not receive the missing mixes error from this rule
Test: Toggle enabled - error assigned
Given: outcome mapping with mixes_missing: true
And: mix results configured for Mix A, Mix B
And: run contains well for Mix A only
When: run is imported
Then: well A shall receive the missing mixes error
Test: Wells with errors are not successful
Given: combined outcome with mixes_missing: true
And: mixes configured for Mix A and Mix B
And: well A1 with Mix A and information-typed LIMS
And: well A2 with Mix B
When: well A2 has error type Label Error, Error, Warning, or Information Typed
Then: well A1 shall receive the mixes missing error
And: well A2 shall not be considered successful
Test: Wells with Warning/Exclude LIMS are not successful
Given: combined outcome with mixes_missing: true
And: mixes configured for Mix A and Mix B
And: well A1 with Mix A and information-typed LIMS
And: well A2 with Mix B
When: well A2 has Warning or Exclude typed LIMS
Then: well A1 shall receive the mixes missing error
And: well A2 shall not be considered successful
Test: Wells with Information LIMS are successful
Given: combined outcome with mixes_missing: true
And: mixes configured for Mix A and Mix B
And: well A1 with Mix A and information-typed LIMS
And: well A2 with Mix B and information-typed LIMS
When: wells are analyzed
Then: well A1 shall not receive the missing mixes error
And: well A2 shall be considered successful
Test: History disabled - current run only
Given: outcome mapping with mixes_missing: true
And: consider_other_runs: false
And: mix results configured for Mix A, Mix B
And: run A contains well AA with Mix A
And: run B contains well BA with Mix B and missing mixes error
When: run A is imported
Then: run A well AA shall receive the missing mix error
And: wells from run B shall not be considered
Test: History enabled - cross-run satisfaction
Given: outcome mapping with mixes_missing: true
And: consider_other_runs: true
And: mix results configured for Mix A, Mix B
And: run A contains well AA with Mix A
And: run B contains well BA with Mix B and missing mixes error
When: run A is imported
Then: run A well AA shall not receive the missing mix error
And: mix requirement shall be satisfied by run B
Test: History well has no error - not eligible
Given: outcome mapping with mixes_missing: true
And: consider_other_runs: true
And: mix results configured for Mix A, Mix B
And: run A contains well AA with Mix A
And: run B contains well BA with Mix B and no error
When: run A is imported
Then: run A well AA shall receive the missing mixes error
And: run B well BA shall not be eligible for cross-run resolution
Test: History well has other error - not eligible
Given: outcome mapping with mixes_missing: true
And: consider_other_runs: true
And: mix results configured for Mix A, Mix B
And: run A contains well AA with Mix A
And: run B contains well BA with Mix B and other error (not missing mixes)
When: run A is imported
Then: run A well AA shall receive the missing mixes error
And: run B well BA shall not be eligible for cross-run resolution
Test: REQ-RULES-MIXMISS-002
Test: Outcome message shows missing mixes
Given: combined outcome with type: error
And: error code: COMBINED_MIXES_WELLS_MISSING
And: missing_mixes: enabled
And: mixes configured for Mix A, Mix B, Mix C
And: well A with accession A and Mix A only
When: well A is analyzed through missing mixes rule
Then: well A shall have error: COMBINED_MIXES_WELLS_MISSING
And: outcome message shall contain Mix B and Mix C
Test: REQ-RULES-MIXMISS-003
Test: All mixes available - status updated
Given: combined outcome with error: COMBINED_MIXES_WELLS_MISSING
And: missing_mixes: enabled
And: use_other_runs: enabled
And: mixes configured for Mix A, Mix B
And: Run A with status: No Resolution
And: Run A well A with accession A, Mix A, missing_mixes: Mix B, error: COMBINED_MIXES_WELLS_MISSING
When: Run B is analyzed with well A having accession A and Mix B
Then: Run A status shall change to "Reanalysis required (Missing mixes uploaded)"
Test: Partial mixes available - status unchanged
Given: combined outcome with error: COMBINED_MIXES_WELLS_MISSING
And: missing_mixes: enabled
And: use_other_runs: enabled
And: mixes configured for Mix A, Mix B, Mix C
And: Run A with status: No Resolution
And: Run A well A with accession A, Mix A, missing_mixes: Mix B, Mix C
When: Run B is analyzed with well A having accession A and Mix B only
Then: Run A status shall remain "No Resolution"
And: Mix C shall still be missing
Test: Existing resolution - status unchanged
Given: combined outcome with error: COMBINED_MIXES_WELLS_MISSING
And: missing_mixes: enabled
And: use_other_runs: enabled
And: mixes configured for Mix A, Mix B
And: Run A with status: Reanalysis required (Westgard)
And: Run A well A with accession A, Mix A, missing_mixes: Mix B
When: Run B is analyzed with well A having accession A and Mix B
Then: Run A status shall remain "Reanalysis required (Westgard)"
And: existing resolution status shall be preserved
Test: REQ-RULES-MIXMISS-004
Test: Execution order verified
Given: combined outcome with multi mix configuration
And: mixes_missing: true
When: well is analyzed
Then: Multi Mix Combined Check shall execute first
And: Multi Mix Missing Check shall execute second
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| Combined Outcome Rule | Multi Mix Combined Outcomes (REQ-RULES-COMBOUT-002) |
| SDD Algorithms | Missing Mixes Algorithm |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated where appropriate (conservative approach for RULES domain)
- 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
Conservative Conversion Notes
This conversion preserved all 4 requirements from the source without consolidation, following the RULES domain guidance for conservative treatment of analytics rules. Each requirement represents a distinct, independently testable capability:
| Original ID | Capability | Disposition |
|---|---|---|
| REQ-RULES-MIXMISS-001 | Missing mixes detection | Preserved - core rule logic |
| REQ-RULES-MIXMISS-002 | Missing mixes tracking/display | Preserved - data persistence behavior |
| REQ-RULES-MIXMISS-003 | Re-analysis status notification | Preserved - run status behavior |
| REQ-RULES-MIXMISS-004 | Rule execution ordering | Preserved - system constraint |
Rationale: Each requirement addresses a different aspect of the missing mixes feature (detection, tracking, status notification, ordering). Consolidation would obscure distinct testable behaviors critical for quality assurance in analytics rules.
Reversibility: Source: output/srs/rules/rule-mixes-missing.md
Readability Conversion Notes
Converted to new SRS format on 2026-01-23:
- Added Statement section for quick understanding
- Added Rule Flowchart (Illustrative) with mermaid decision diagram
- Changed "(Non-normative)" to "(Illustrative)" throughout
- Grouped acceptance criteria by concern with blank lines before bullet lists
- Added Inputs/Outputs tables to requirements
- Added Error Handling sections
- Moved tests to end with back-links to requirements
- Added Open Questions for error handling gaps
- Preserved all REQ-* identifiers, ACs, and traceability references