Extraction Controls Rule (MINEXTRACT)
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: MINEXTRACT rule for validating patient wells have associated positive and negative extraction controls Domain: RULES-EXTCTRL Precedence: TBD (rule_priority in config)
Statement
The system shall validate that patient sample wells have matching positive and negative extraction controls (PEC/NEC) based on extraction details including mix, extraction date, instrument, and batch number.
When a patient well lacks matching controls for its primary mix, the system checks the fallback shared control setting. If enabled, the system searches for controls using a configured backup mix. Control wells with label-type errors are excluded from consideration. The "Quantification & PC" role type is accepted as a valid positive extraction control.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-EXTCTRL-001 | Validates PEC/NEC presence for patient wells | HIGH | Draft |
| REQ-RULES-EXTCTRL-002 | Reports error when fallback disabled and controls missing | HIGH | Draft |
| REQ-RULES-EXTCTRL-003 | Searches backup mix when fallback enabled | HIGH | Draft |
| REQ-RULES-EXTCTRL-004 | Recognizes "Quantification & PC" as positive control | MEDIUM | Draft |
| REQ-RULES-EXTCTRL-005 | Excludes label error wells from MINEXTRACT control association | HIGH | Draft |
| REQ-RULES-EXTCTRL-006 | Excludes label error wells from MINCONTROL control association | HIGH | Draft |
Key Integration Points: Well Data Management, Kit Configuration, Error Handling System, Resolution Management
Rule Summary
| Property | Value |
|---|---|
| Name | MINEXTRACT |
| Precedence | TBD (in config sheet) |
| Triggers | When evaluating patient well extraction control requirements |
| Output | Assigns EXTRACTION_CONTROLS_MISSING error or passes |
Rule Flowchart (Illustrative)
This diagram illustrates the core MINEXTRACT decision logic. Role type recognition ("Quantification & PC" as PEC) and MINCONTROL rule behavior follow similar patterns.
Definitions
| Term | Definition |
|---|---|
| MINEXTRACT | Rule identifier for extraction controls validation |
| MINCONTROL | Related rule for general control validation (REQ-RULES-EXTCTRL-006) |
| PEC | Positive Extraction Control - a control well of type PC or "Quantification & PC" |
| NEC | Negative Extraction Control - a control well of type NC |
| Extraction Details | The combination of mix, extraction date, extraction instrument, and batch number |
| Fallback Shared Control | Feature that enables checking backup mix when primary mix controls are missing |
| Backup Mix | Alternative mix defined in role-target mappings for fallback control matching |
| Label Error | A category of error indicating uncertain well identity/contents |
Assumptions
- Patient wells are identified by role_alias "Patient" or equivalent non-Control designation
- Control wells have role configurations with has_extraction attribute
- Error codes have a type classification that distinguishes Label Errors from other error types
- Role-target mappings define backup_mix when fallback shared control feature is used
Requirements
Core Validation (REQ-RULES-EXTCTRL-001)
FR-EXTCTRL-001: Validate Patient Well Extraction Controls
The system shall validate that patient sample wells have matching positive and negative extraction controls based on extraction details.
Inputs/Outputs
| Direction | Data | Source/Target |
|---|---|---|
| Input | Patient well observations (role, mix, extraction date, instrument, batch) | Well Data |
| Input | Control well observations (PEC/NEC type, extraction details) | Well Data |
| Input | Role configurations (has_extraction attribute) | Kit Configuration |
| Output | Error code EXTRACTION_CONTROLS_MISSING | Well record |
Acceptance Criteria
Control Matching:
- Validate that a sample well has both a matching PEC and matching NEC
- Matching requires the control well to have the same mix as the patient well
- Matching requires the control well to have the same extraction date as the patient well
- Matching requires the control well to have the same extraction instrument as the patient well
- Matching requires the control well to have the same batch number as the patient well (when batch number is present)
Error Assignment:
- When validation fails, assign error code
EXTRACTION_CONTROLS_MISSINGto the well - When patient well missing matching PEC, assign error
EXTRACTION_CONTROLS_MISSING - When patient well missing matching NEC, assign error
EXTRACTION_CONTROLS_MISSING
Skip Conditions:
- Given a well with role_alias "Control", when MINEXTRACT executes, then skip (no errors)
- Given a patient well with resolution code "MINEXTRACT", when MINEXTRACT executes, then skip (no errors)
Trace: Source: 3.0.0-Extraction controls rule (Rows 1-6) | Jira: BT-1216, BT-3917 | Tests: See scenarios
Fallback Behavior (REQ-RULES-EXTCTRL-002, REQ-RULES-EXTCTRL-003)
FR-EXTCTRL-002: Report Error When Fallback Disabled
The system shall assign an error when extraction controls are missing for a patient well's primary mix and the fallback shared control feature is disabled.
Acceptance Criteria
Fallback Check:
- When no matching PEC and NEC are found for patient well's primary mix, check the fallback shared control setting
- When fallback shared control is disabled, assign error code
EXTRACTION_CONTROLS_MISSINGto the well
Trace: Source: 3.0.0-Extraction controls rule (Row 7) | Jira: BT-3883 | Tests: See scenarios | Related: REQ-RULES-EXTCTRL-001, REQ-RULES-EXTCTRL-003
FR-EXTCTRL-003: Check Backup Mix When Fallback Enabled
The system shall search for matching extraction controls using the configured backup mix when the patient well's primary mix has no matching controls and the fallback shared control feature is enabled.
Acceptance Criteria
Fallback Search:
- When no matching PEC and NEC are found for patient well's primary mix, check the fallback shared control setting
- When fallback shared control is enabled, search for matching controls using the backup mix defined in role to target mappings
- When matching controls are found via backup mix, no error shall be assigned to the patient well
Trace: Source: 3.0.0-Extraction controls rule (Row 8) | Jira: BT-3883 | Tests: See scenarios | Related: REQ-RULES-EXTCTRL-001, REQ-RULES-EXTCTRL-002
Role Type Recognition (REQ-RULES-EXTCTRL-004)
FR-EXTCTRL-004: Recognize Quantification and PC Role as Positive Control
The system shall accept wells with role type "Quantification & PC" as valid positive extraction controls when evaluating extraction control requirements.
Acceptance Criteria
Valid Positive Control Types:
- Role type "Quantification & PC" shall be treated as a positive extraction control in MINEXTRACT evaluation
- The system shall recognize the following role types as positive extraction controls:
- "PC" (Positive Control)
- "Quantification & PC" (dual-purpose role)
Trace: Source: 3.0.0-Min Extraction Rule - Consider Quantitative Standard Role (Row 1) | Jira: BT-4376 | Tests: See scenarios | Related: REQ-RULES-EXTCTRL-001
Label Error Exclusion (REQ-RULES-EXTCTRL-005, REQ-RULES-EXTCTRL-006)
FR-EXTCTRL-005: Exclude Label Error Wells from MINEXTRACT Control Association
The system shall exclude wells with label-type errors from consideration as valid associated extraction controls when evaluating the MINEXTRACT rule.
Acceptance Criteria
Error Type Handling:
- Wells with label-type errors shall not be considered as valid extraction controls
- Wells with non-label-type errors shall still be considered as valid extraction controls
Label Error Exclusion Logic:
| Error Type | Control Validity |
|---|---|
| Label Error | Excluded from control matching |
| Non-Label Error | Included in control matching |
Trace: Source: 3.0.0-MinExtract Rule - Label Error wells Should not be considered as Associated Controls (Row 1) | Jira: BT-4719 | Tests: See scenarios | Related: REQ-RULES-EXTCTRL-001, REQ-RULES-EXTCTRL-006
FR-EXTCTRL-006: Exclude Label Error Wells from MINCONTROL Control Association
The system shall exclude wells with label-type errors from consideration as valid associated controls when evaluating the MINCONTROL rule.
Acceptance Criteria
Error Type Handling:
- Wells with label-type errors shall not be considered as valid associated controls
- Wells with non-label-type errors shall still be considered as valid associated controls
Assumptions
- This requirement applies to the MINCONTROL rule, which is distinct from the MINEXTRACT rule but follows similar label error exclusion logic
Trace: Source: 3.0.0-MinControl Rule - Label Error wells Should not be considered as Associated Controls (Row 1) | Jira: BT-4719 | Tests: See scenarios | Related: REQ-RULES-EXTCTRL-005
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
fallback_shared_control | false | Enable backup mix fallback when primary mix controls missing | REQ-RULES-EXTCTRL-002, REQ-RULES-EXTCTRL-003 |
rule_priority | TBD | Rule execution priority in processing sequence | REQ-RULES-EXTCTRL-001 |
allowed_resolutions | [MINEXTRACT] | Resolution codes that bypass the rule | REQ-RULES-EXTCTRL-001 |
Open Questions
| ID | Question | Source | Owner | Date Raised |
|---|---|---|---|---|
| OQ-001 | What is the priority for this rule in config sheet? | Config | TBD | Open |
| OQ-002 | What resolutions should be allowed for this rule in config? | Config | TBD | Open |
Notes
- REQ-RULES-EXTCTRL-006 applies to the MINCONTROL rule (separate from MINEXTRACT) but is included here due to shared label error exclusion logic documented in the same Confluence source
- The MINEXTRACT rule uses a decision tree pattern: check if patient well -> check resolution -> validate PEC -> validate NEC
UI Notes (Illustrative)
No UI-specific details identified in source material. This rule operates at the analytics engine level without direct UI interaction.
Implementation (Illustrative)
| Component | Location | Purpose |
|---|---|---|
| MinextractRule | Analyzer/Rules/MinextractRule.php | Core extraction controls validation - PEC/NEC matching, fallback support |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-EXTCTRL-001 | Validate Patient Well Extraction Controls | Test | MinextractRule.php | Scenarios | Draft |
| REQ-RULES-EXTCTRL-002 | Report Error When Fallback Disabled | Test | MinextractRule.php | Scenarios | Draft |
| REQ-RULES-EXTCTRL-003 | Check Backup Mix When Fallback Enabled | Test | MinextractRule.php | Scenarios | Draft |
| REQ-RULES-EXTCTRL-004 | Recognize Quantification and PC Role as Positive Control | Test | MinextractRule.php | Scenarios | Draft |
| REQ-RULES-EXTCTRL-005 | Exclude Label Error Wells from MINEXTRACT Control Association | Test | MinextractRule.php | Scenarios | Draft |
| REQ-RULES-EXTCTRL-006 | Exclude Label Error Wells from MINCONTROL Control Association | Test | MinextractRule.php | Scenarios | Draft |
Acceptance Tests
Test: REQ-RULES-EXTCTRL-001
Test: Non-patient well skipped
Given: Well well1 with role_alias "Control"
When: MINEXTRACT rule executes for well1
Then: well1 shall have no errors (rule skipped)
Test: Resolution bypass
Given: Well well1 with role_alias "Patient" and resolution_codes [MINEXTRACT]
When: MINEXTRACT rule executes for well1
Then: well1 shall have no errors (rule skipped due to resolution)
Test: Valid extraction controls present
Given: Patient well with matching PEC and NEC (same mix, extraction date, instrument, batch)
When: MINEXTRACT rule executes
Then: Patient well shall have no error
Test: Missing extraction controls
Given: Patient well without matching PEC or NEC
When: MINEXTRACT rule executes
Then: Patient well shall receive error EXTRACTION_CONTROLS_MISSING
Test: REQ-RULES-EXTCTRL-002
Test: Fallback disabled missing controls
Given: Extraction Instrument EI-1
And: Roles role1 (type: PC, has_extraction: true), role2 (type: NC, has_extraction: true)
And: Mixes mix1, mix2
And: Target target1 (mix: mix1)
And: Role to target mappings with backup_mix: mix2
And: Control wells (well1, well2) with mix1, extraction date 2023-05-31, batch 12, instrument EI-1
And: Patient well (well3) with mix2, extraction date 2023-05-31, batch 12, instrument EI-1
And: Fallback shared control is disabled
When: MINEXTRACT rule executes for well3
Then: well3 shall receive error EXTRACTION_CONTROLS_MISSING
Test: REQ-RULES-EXTCTRL-003
Test: Fallback enabled finds backup controls
Given: Extraction Instrument EI-1
And: Roles role1 (type: PC, has_extraction: true), role2 (type: NC, has_extraction: true)
And: Mixes mix1, mix2
And: Target target1 (mix: mix1)
And: Role to target mappings with backup_mix: mix2
And: Control wells (well1, well2) with mix1, extraction date 2023-05-31, batch 12, instrument EI-1
And: Patient well (well3) with mix2, extraction date 2023-05-31, batch 12, instrument EI-1
And: Fallback shared control is enabled
When: MINEXTRACT rule executes for well3
Then: well3 shall have no error
Test: REQ-RULES-EXTCTRL-004
Test: Quantification & PC role accepted as PEC
Given: Patient well A1
And: Control well A2 with role type "Quantification & PC" and role is_extracted true
And: Control well A3 with role type "NC" and role is_extracted true
And: Associated extraction controls properly linked
When: Patient well A1 is analyzed through the MINEXTRACT rule
Then: Patient well A1 shall not receive EXTRACTION_CONTROLS_MISSING error
Test: REQ-RULES-EXTCTRL-005
Test: Non-label error control accepted
Given: Sample well A1 with extraction-details X
And: Pos Control well A2 with extraction-details X and error EXAMPLE_ERROR
And: Neg Control well A3 with extraction-details X
And: Error code EXAMPLE_ERROR is NOT a Label Error type
When: MINEXTRACT rule executes for A1
Then: Sample well A1 shall not receive min extraction controls error
Test: Label error control excluded
Given: Sample well A1 with extraction-details X
And: Pos Control well A2 with extraction-details X and error EXAMPLE_ERROR
And: Neg Control well A3 with extraction-details X
And: Error code EXAMPLE_ERROR IS a Label Error type
When: MINEXTRACT rule executes for A1
Then: Sample well A1 shall receive min extraction controls error
Test: REQ-RULES-EXTCTRL-006
Test: Non-label error control accepted (MINCONTROL)
Given: Sample well A1
And: Pos Control well A2 with error EXAMPLE_ERROR
And: Neg Control well A3
And: Error code EXAMPLE_ERROR is NOT a Label Error type
When: MinControl rule executes for A1
Then: Sample well A1 shall not receive min controls error
Test: Label error control excluded (MINCONTROL)
Given: Sample well A1
And: Pos Control well A2 with error EXAMPLE_ERROR
And: Neg Control well A3
And: Error code EXAMPLE_ERROR IS a Label Error type
When: MinControl rule executes for A1
Then: Sample well A1 shall receive min controls error
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | Extraction Controls 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 Applied
All 6 requirements from the source were preserved as individual requirements:
| Requirement | Capability | Justification |
|---|---|---|
| REQ-RULES-EXTCTRL-001 | Core extraction control validation | Primary rule logic - distinct validation capability |
| REQ-RULES-EXTCTRL-002 | Fallback disabled behavior | Distinct outcome behavior when feature off |
| REQ-RULES-EXTCTRL-003 | Fallback enabled behavior | Distinct outcome behavior when feature on |
| REQ-RULES-EXTCTRL-004 | Role type extension | Distinct analytical logic for "Quantification & PC" |
| REQ-RULES-EXTCTRL-005 | Label error exclusion (MINEXTRACT) | Distinct error handling logic |
| REQ-RULES-EXTCTRL-006 | Label error exclusion (MINCONTROL) | Separate rule entirely |
Rationale: These requirements represent distinct analytical behaviors in a RULES domain where precision is critical. The fallback enabled/disabled behaviors produce different outcomes. Label error exclusion logic affects different rules (MINEXTRACT vs MINCONTROL). Role type recognition extends the positive control type set. Conservative consolidation approach applied per RULES domain guidance.
Reversibility: Source preserved at:
- Source:
output/pilot/rules/rule-extraction-controls/rule-extraction-controls-restructured.md - SDD:
output/pilot/rules/rule-extraction-controls/sdd/rule-extraction-controls-design.md