MIN_CONTROLS Rule

Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: Validates patient wells have required positive and negative controls within the same run Domain: RULES-MINCTRL Precedence: Quality control validation rule

---

Statement

The system shall validate that patient wells have the required positive and negative controls available within the same run before processing.

The rule evaluates each patient well against configured role-to-target mappings to ensure matching PC (positive control) and NC (negative control) wells exist. When controls are missing from the primary mix, an optional fallback mechanism can check a configured backup mix. Wells that fail control validation receive a CONTROL_MISSING error code.

---

Quick Reference

ID	Core Behavior	Priority	Status
REQ-RULES-MINCTRL-001	Skips rule for non-patient wells	HIGH	Draft
REQ-RULES-MINCTRL-002	Skips rule when MINCONTROL resolution exists	HIGH	Draft
REQ-RULES-MINCTRL-003	Assigns CONTROL_MISSING when fallback disabled and controls missing	HIGH	Draft
REQ-RULES-MINCTRL-004	Checks backup mix when fallback enabled and primary controls missing	HIGH	Draft

Key Integration Points: Well Management, Role-to-Target Mapping, Error Assignment, Feature Configuration

Rule Summary

Property	Value
Name	MIN_CONTROLS
Error Code	CONTROL_MISSING
Triggers	When evaluating patient wells for control presence
Output	CONTROL_MISSING error or no error

---

Rule Flowchart (Illustrative)

This diagram illustrates the rule's decision logic. Each requirement maps to a specific decision point in the flow.

---

Definitions

Term	Definition
Patient Well	A well with role_alias set to "Patient", containing patient sample for analysis
Control Well	A well with role_alias set to "Control", containing known reference material
PC (Positive Control)	A control well containing known positive sample for validation
NC (Negative Control)	A control well containing known negative sample for validation
Mix	A grouping of wells that share common processing parameters
Backup Mix	An alternative mix configuration checked when primary controls are missing
Role-to-Target Mapping	Configuration defining which control roles are required for specific targets
Resolution Code	Status code assigned to a well indicating processing outcome or override
Fallback Shared Control	Feature enabling backup mix controls to satisfy control requirements

---

Assumptions

• Wells have been assigned a role_alias value (Patient, Control, etc.)
• Role-to-target mappings are configured for the assay
• Control wells exist in the run (though may not match all mixes)
• The fallback_shared_control configuration option is set before rule execution

---

Requirements

Skip Conditions (REQ-RULES-MINCTRL-001, 002)

FR-MINCTRL-001: Skip Rule for Non-Patient Wells

The system shall skip the MIN_CONTROLS rule execution when the target well is not a patient well.

Acceptance Criteria

Role Evaluation:

• Evaluate the well's role_alias attribute to determine patient status
• Wells with role_alias values other than "Patient" shall be skipped

Skip Behavior:

• Skipped wells shall not receive any errors from this rule
• No further rule processing shall occur for non-patient wells

Trace: Source: 3.0.0-MINCONTROLS RULE / Requirements Table (Row 1, Lines 27-46) | Jira: BT-3883 | Epic: BT-3864 | Tests: BT-3918, See scenarios

---

FR-MINCTRL-002: Skip Rule When MINCONTROL Resolution Exists

The system shall skip the MIN_CONTROLS rule execution when the well already has a MINCONTROL resolution code assigned.

Acceptance Criteria

Resolution Check:

• Check the well's resolution codes before processing
• If "MINCONTROL" resolution code is present, skip all further logic

Skip Behavior:

• Wells with MINCONTROL resolution shall not receive any errors from this rule
• Other resolution codes shall not trigger the skip behavior

Trace: Source: 3.0.0-MINCONTROLS RULE / Requirements Table (Row 2, Lines 47-60) | Epic: BT-3864 | Tests: See scenarios

---

Control Validation (REQ-RULES-MINCTRL-003, 004)

FR-MINCTRL-003: Set CONTROL_MISSING Error When Fallback Disabled

The system shall assign the CONTROL_MISSING error code to a patient well when no matching positive or negative control is found in the primary mix and the fallback shared control feature is disabled.

Acceptance Criteria

Control Identification:

• Identify required control roles from role-to-target mappings
• Determine required control types from role-to-target mappings with type PC or NC
• Search for control wells matching the patient well's mix
• Match controls based on mix association between patient well and control wells

Error Assignment:

• When no matching PC controls are found for required mappings, CONTROL_MISSING shall apply
• When no matching NC controls are found for required mappings, CONTROL_MISSING shall apply
• Error code CONTROL_MISSING shall be assigned to the patient well

Fallback Restriction:

• The rule shall not consult backup_mix configuration when fallback is disabled

Error Handling

• No matching PC in primary mix (fallback disabled): Assign CONTROL_MISSING error to patient well
• No matching NC in primary mix (fallback disabled): Assign CONTROL_MISSING error to patient well

Trace: Source: 3.0.0-MINCONTROLS RULE / Requirements Table (Row 3, Lines 62-121) | Epic: BT-3864 | Tests: See scenarios | Related: REQ-RULES-MINCTRL-004

---

FR-MINCTRL-004: Check Backup Mix Controls When Fallback Enabled

The system shall check the backup mix configuration for available controls when no matching positive or negative control is found in the primary mix and the fallback shared control feature is enabled.

Acceptance Criteria

Primary Check:

• First check for controls matching the patient well's mix
• When no direct match found, consult the backup_mix from role-to-target mappings

Backup Mix Resolution:

• If control wells exist for the backup mix, the control requirement shall be satisfied
• No error shall be assigned when backup mix controls satisfy the requirement
• The fallback mechanism shall use the backup_mix field defined in role-to-target mappings
• The backup mix shall be defined per role-to-target mapping, allowing flexible control sharing configurations
• Each role-to-target mapping may specify a different backup_mix value

Error Assignment:

• If neither primary nor backup mix has required controls, CONTROL_MISSING shall apply

Error Handling

• No matching controls in primary mix, backup mix has controls: No error assigned
• No matching controls in primary or backup mix: Assign CONTROL_MISSING error to patient well

Trace: Source: 3.0.0-MINCONTROLS RULE / Requirements Table (Row 4, Lines 123-182) | Jira: BT-3883 | Epic: BT-3864 | Tests: See scenarios | Related: REQ-RULES-MINCTRL-003

---

Configuration Options

Option	Default	Description	Affects
fallback_shared_control	disabled	When enabled, allows backup mix controls to satisfy control requirements when primary mix controls are missing	REQ-RULES-MINCTRL-003, REQ-RULES-MINCTRL-004

Configuration Impact Matrix

Scenario	fallback_shared_control	Primary Mix Has Controls	Backup Mix Has Controls	Result
A	disabled	Yes	N/A	No error
B	disabled	No	N/A	CONTROL_MISSING
C	enabled	Yes	N/A	No error
D	enabled	No	Yes	No error
E	enabled	No	No	CONTROL_MISSING

---

Notes

• Rule Code: MIN_CONTROLS
• Error Code: CONTROL_MISSING
• Context diagram available: See media/image160.png for rule flow visualization
• This rule implements the "shared controls" feature from Epic BT-3864 (Quest: Fallback (shared) controls)

---

Implementation (Illustrative)

Component	Location
MinControlsRule	Analyzer/Rules/MinControlsRule.php

---

Traceability Matrix

Requirement	Title	Verification	Implementation	Test Cases	Status
REQ-RULES-MINCTRL-001	Skip Rule for Non-Patient Wells	Test	MinControlsRule	BT-3918	Draft
REQ-RULES-MINCTRL-002	Skip Rule When MINCONTROL Resolution Exists	Test	MinControlsRule	[Pending]	Draft
REQ-RULES-MINCTRL-003	Set CONTROL_MISSING Error When Fallback Disabled	Test	MinControlsRule	[Pending]	Draft
REQ-RULES-MINCTRL-004	Check Backup Mix Controls When Fallback Enabled	Test	MinControlsRule	BT-3918	Draft

---

Acceptance Tests

Test: REQ-RULES-MINCTRL-001

Back to requirement

Test: Control well skipped by rule

Given:
  Well:
    well1:
      role_alias: Control

When:
  Execute MIN_CONTROLS rule for well1

Then:
  well1 has no errors

---

Test: REQ-RULES-MINCTRL-002

Back to requirement

Test: Patient well with MINCONTROL resolution skipped

Given:
  Well:
    well1:
      role_alias: Patient
      resolution codes: MINCONTROL

When:
  Execute MIN_CONTROLS rule for well1

Then:
  well1 has no errors

---

Test: REQ-RULES-MINCTRL-003

Back to requirement

Test: Missing controls with fallback disabled assigns error

Given:
  Error code: CONTROL_MISSING
  Roles:
    role1:
      type: PC
    role2:
      type: NC

  Mixes:
    mix1:
      mix_name: mix1
    mix2:
      mix_name: mix2

  Targets:
    target1:
      mix: mix1

  Role to target mappings:
    Mapping1:
      role: role1
      target: target1
      mix: mix1
      backup_mix: mix2
    Mapping2:
      role: role2
      target: target1
      mix: mix1
      backup_mix: mix2

  Wells:
    well1:
      role alias: Control
      mix: mix1
      observations:
        role: role1
        role to target mapping: Mapping1

    well2:
      role alias: Control
      mix: mix1
      observations:
        role: role2
        role to target mapping: Mapping2

    well3:
      role alias: Patient
      mix: mix2
      observations: (none)

When:
  fallback shared control: disabled
  MIN_CONTROLS rule execute for well3

Then:
  Well 3 get error CONTROL_MISSING

---

Test: REQ-RULES-MINCTRL-004

Back to requirement

Test: Missing primary controls satisfied by backup mix

Given:
  Error code: CONTROL_MISSING
  Roles:
    role1:
      type: PC
    role2:
      type: NC

  Mixes:
    mix1:
      mix_name: mix1
    mix2:
      mix_name: mix2

  Targets:
    target1:
      mix: mix1

  Role to target mappings:
    Mapping1:
      role: role1
      target: target1
      mix: mix1
      backup_mix: mix2
    Mapping2:
      role: role2
      target: target1
      mix: mix1
      backup_mix: mix2

  Wells:
    well1:
      role alias: Control
      mix: mix1
      observations:
        role: role1
        role to target mapping: Mapping1

    well2:
      role alias: Control
      mix: mix1
      observations:
        role: role2
        role to target mapping: Mapping2

    well3:
      role alias: Patient
      mix: mix2
      observations: (none)

When:
  fallback shared control: enabled
  MIN_CONTROLS rule execute for well3

Then:
  Well 3 has no error

---

Related Design Documents

Design Document	Relevant Sections
SDD Algorithms	Control Validation Algorithm

---

Appendix: Process Artifacts

Completion Checklist

• All requirements are capability-level (describe behavior, not UI)
• Requirement variants consolidated (no requirement explosion) - N/A, no consolidation needed
• 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, no open questions
• 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

The four requirements in this domain represent distinct rule behaviors in the MIN_CONTROLS rule execution path:

Requirement	Purpose	Consolidation Decision
REQ-RULES-MINCTRL-001	Skip condition for non-patient wells	Preserved - distinct entry condition
REQ-RULES-MINCTRL-002	Skip condition for resolution override	Preserved - distinct entry condition
REQ-RULES-MINCTRL-003	Error assignment when fallback disabled	Preserved - distinct outcome path
REQ-RULES-MINCTRL-004	Fallback behavior when enabled	Preserved - distinct outcome path

Rationale: These requirements represent separate decision points in the rule flow diagram. Each has distinct test scenarios and affects different aspects of rule behavior. Consolidation would lose precision required for analytics rule validation.

Reversibility: Source requirements preserved 1:1.

• Source: output/pilot/rules/rule-mincontrols/rule-mincontrols-restructured.md