Positive Sigmoid Rule
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: POSITIVE_SIGMOID rule for validating sigmoid curve direction on positive wells Domain: RULES-POSSIGMOID Precedence: Part of sigmoid rule validation suite
Statement
The system shall validate that wells with a positive final classification exhibit the expected upward sigmoid curve shape and flag errors when an incorrect downward pattern is detected.
This rule is part of the Sigmoid Rule Update initiative that separates sigmoid validation into distinct rules for positive and negative wells, improving the specificity of curve validation errors. The companion rule NEGATIVE_SIGMOID handles validation for negative wells.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-POSSIGMOID-001 | Flag positive wells with incorrect downward sigmoid curve | HIGH | Draft |
| REQ-RULES-POSSIGMOID-002 | Skip check when resolution code POSITIVE_SIGMOID is present | HIGH | Draft |
| REQ-RULES-POSSIGMOID-003 | Skip check when manual classification is present | HIGH | Draft |
Key Integration Points: Well Classification System, Run Processing Engine, Error Code Assignment, Resolution Code System
Rule Summary
| Property | Value |
|---|---|
| Name | POSITIVE_SIGMOID |
| Triggers | When processing wells with positive final classification |
| Output | Sets INCORRECT_POSITIVE_SIGMOID (well) and INCORRECT_POSITIVE_SIGMOID_TARGET (target) error codes |
| Resolution Code | POSITIVE_SIGMOID |
Rule Flowchart (Illustrative)
This diagram illustrates the rule evaluation logic. Skip conditions are evaluated first, then classification and sigmoid direction checks.
Definitions
| Term | Definition |
|---|---|
| Sigmoid Curve | The characteristic S-shaped amplification curve produced during PCR |
| Upward Sigmoid | A sigmoid curve where signal increases over cycles (expected for positive wells) |
| Downward Sigmoid | A sigmoid curve where signal decreases over cycles (unexpected for positive wells) |
| final_cls | The final classification assigned to a well (positive, negative, etc.) |
| manual_cls | A classification manually assigned by a user, overriding automated classification |
| Resolution Code | A user-applied code that acknowledges and dismisses a specific error condition |
Assumptions
- Wells have been processed and assigned a final classification before this rule executes
- Sigmoid curve direction can be algorithmically determined from observation readings
- Resolution codes and manual classifications are applied prior to rule execution
- The rule executes as part of the standard run processing pipeline
Requirements
Sigmoid Curve Validation (REQ-RULES-POSSIGMOID-001)
FR-POSSIGMOID-001: Flag Positive Wells with Incorrect Sigmoid Curve Direction
The system shall evaluate wells with a positive final classification and assign error codes when the sigmoid curve direction is downward instead of the expected upward pattern.
Acceptance Criteria
Error Detection:
- Given a well with downward sigmoid and final_cls: positive, the well shall have error_code: INCORRECT_POSITIVE_SIGMOID and the target shall have error_code: INCORRECT_POSITIVE_SIGMOID_TARGET
Correct Pattern Handling:
- Given a well with upward sigmoid and final_cls: positive, the well shall have no error and the target shall have no error
- The rule shall only check for INCORRECT sigmoid patterns; correct patterns (upward sigmoid on positive wells) shall pass without flagging
Scope Exclusions:
- Given a well with downward sigmoid and final_cls: negative, the well shall have no error and the target shall have no error
- Given a well with upward sigmoid and final_cls: negative, the well shall have no error and the target shall have no error
- The rule shall specifically target positive wells; wells with negative final classification shall be out of scope for this rule
Error Code Assignment:
- The system shall assign error codes at two levels: well (INCORRECT_POSITIVE_SIGMOID) and target (INCORRECT_POSITIVE_SIGMOID_TARGET)
Error Handling
- Downward sigmoid detected on positive well: The system shall assign INCORRECT_POSITIVE_SIGMOID to well and INCORRECT_POSITIVE_SIGMOID_TARGET to target
Trace: Source: 3.0.0-Positive Sigmoid Rule (Row 1) | Jira: BT-5014 | Epic: BT-5015 | Tests: BT-5021, See scenarios
Skip Conditions (REQ-RULES-POSSIGMOID-002 & 003)
FR-POSSIGMOID-002: Skip Positive Sigmoid Check When Resolution Code Is Present
The system shall skip execution of the POSITIVE_SIGMOID rule check entirely when a well has the resolution code POSITIVE_SIGMOID applied.
Acceptance Criteria
Resolution Code Handling:
- Given a well with downward sigmoid, final_cls: positive, and resolution_code: POSITIVE_SIGMOID, the well shall have no error and the target shall have no error
- The resolution code mechanism shall provide a way to acknowledge and dismiss the sigmoid warning
- The resolution code value shall be POSITIVE_SIGMOID
Trace: Source: 3.0.0-Positive Sigmoid Rule (Row 2) | Jira: BT-5014 | Tests: See scenarios
FR-POSSIGMOID-003: Skip Positive Sigmoid Check When Manual Classification Is Present
The system shall skip execution of the POSITIVE_SIGMOID rule check entirely when a well has a manual classification assigned.
Acceptance Criteria
Manual Classification Handling:
- Given a well with downward sigmoid, final_cls: positive, and manual_cls: positive, the well shall have no error and the target shall have no error
- The skip shall apply regardless of what value the manual classification is set to
- Manual classification shall indicate user intent; automated validation shall be bypassed
Trace: Source: 3.0.0-Positive Sigmoid Rule (Row 3) | Jira: BT-5014 | Tests: See scenarios
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
resolution_code_positive_sigmoid | POSITIVE_SIGMOID | Resolution code that allows users to dismiss the INCORRECT_POSITIVE_SIGMOID error | REQ-RULES-POSSIGMOID-002 |
Note: Unlike some other rules, the POSITIVE_SIGMOID rule does not have configurable thresholds. The rule evaluates the sigmoid curve shape algorithmically.
Notes
- This rule was created as part of the Sigmoid Rule Update (BT-5015) that separates sigmoid validation into distinct rules for positive and negative wells
- The companion rule NEGATIVE_SIGMOID handles validation for negative wells
- Design decision: Errors are assigned at both well and target levels for comprehensive tracking and reporting capabilities
- Design decision: Skip precedence places manual classification and resolution codes before rule evaluation, preventing any error assignment when either is present
UI Notes (Illustrative)
Error Code Display
- INCORRECT_POSITIVE_SIGMOID errors display at the well level in the run results interface
- INCORRECT_POSITIVE_SIGMOID_TARGET errors display at the target level for tracking purposes
Sigmoid Curve Visual Reference
Upward Sigmoid (Expected for Positive Wells):
Signal
^
| .---------
| /
| /
| /
|----'
+-------------------> Cycles
Downward Sigmoid (Error for Positive Wells):
Signal
^
|-----.
| \
| \
| \
| `---------
+-------------------> Cycles
Implementation (Illustrative)
| Component | Location |
|---|---|
| Rule Class | Analyzer/Rules/PositiveSigmoidRule.php |
| Sigmoid Identifier | Support/SigmoidIdentifier.php |
| Error Setter | Analyzer/Rules/Concerns/SetErrorToWell.php |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-POSSIGMOID-001 | Flag Positive Wells with Incorrect Sigmoid Curve Direction | Test | PositiveSigmoidRule | BT-5021 | Draft |
| REQ-RULES-POSSIGMOID-002 | Skip Positive Sigmoid Check When Resolution Code Is Present | Test | PositiveSigmoidRule | [Pending] | Draft |
| REQ-RULES-POSSIGMOID-003 | Skip Positive Sigmoid Check When Manual Classification Is Present | Test | PositiveSigmoidRule | [Pending] | Draft |
Acceptance Tests
Test: REQ-RULES-POSSIGMOID-001
Test: Downward sigmoid on positive well produces error
Given: A well with observation readings showing downward sigmoid
And: The well has final_cls: positive
When: The well is processed through the POSITIVE_SIGMOID rule
Then: The well shall have error_code: INCORRECT_POSITIVE_SIGMOID
And: The target shall have error_code: INCORRECT_POSITIVE_SIGMOID_TARGET
Test: Downward sigmoid on negative well produces no error
Given: A well with observation readings showing downward sigmoid
And: The well has final_cls: negative
When: The well is processed through the POSITIVE_SIGMOID rule
Then: The well shall have no error
And: The target shall have no error
Test: Upward sigmoid on negative well produces no error
Given: A well with observation readings showing upward sigmoid
And: The well has final_cls: negative
When: The well is processed through the POSITIVE_SIGMOID rule
Then: The well shall have no error
And: The target shall have no error
Test: Upward sigmoid on positive well produces no error
Given: A well with observation readings showing upward sigmoid
And: The well has final_cls: positive
When: The well is processed through the POSITIVE_SIGMOID rule
Then: The well shall have no error
And: The target shall have no error
Test: REQ-RULES-POSSIGMOID-002
Test: Resolution code skips rule execution
Given: A well with observation readings showing downward sigmoid
And: The well has final_cls: positive
And: The well has resolution_code: POSITIVE_SIGMOID
When: The well is processed through the POSITIVE_SIGMOID rule
Then: The well shall have no error
And: The target shall have no error
Test: REQ-RULES-POSSIGMOID-003
Test: Manual classification skips rule execution
Given: A well with observation readings showing downward sigmoid
And: The well has final_cls: positive
And: The well has manual_cls: positive
When: The well is processed through the POSITIVE_SIGMOID rule
Then: The well shall have no error
And: The target shall have no error
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion) - N/A: No explosion detected
- 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 folded into acceptance criteria
- Traceability matrix is complete
Reviewer Notes
No Consolidation Required
The three requirements in this domain represent distinct system capabilities:
| Requirement | Capability | Rationale for Keeping Separate |
|---|---|---|
| REQ-RULES-POSSIGMOID-001 | Core rule logic - detect incorrect sigmoid | Primary rule functionality |
| REQ-RULES-POSSIGMOID-002 | Skip on resolution code | Distinct skip mechanism with specific resolution code |
| REQ-RULES-POSSIGMOID-003 | Skip on manual classification | Distinct skip mechanism with different trigger |
Rationale: Per RULES domain guidance, conservative consolidation is required. These three requirements represent independently testable behaviors with distinct test scenarios. No consolidation is appropriate.
Reversibility: Source requirements preserved 1:1.
- Source:
output/pilot/rules/rule-positive-sigmoid/rule-positive-sigmoid-restructured.md