1 files changed, 169 insertions, 0 deletions
diff --git a/js/scripting-lang/design/INVESTIGATE.md b/js/scripting-lang/design/INVESTIGATE.md
new file mode 100644
index 0000000..7af4a74
--- /dev/null
+++ b/js/scripting-lang/design/INVESTIGATE.md
@@ -0,0 +1,169 @@
+# Investigation: Known and Suspected Problems
+
+This document tracks known issues, suspected problems, and areas that need investigation in the scripting language implementation.
+
+## Known Issues
+
+### 1. Boolean Pattern Matching Bug
+
+**Problem**: Boolean values in `when` expressions are incorrectly matched against wildcard patterns.
+
+**Evidence**:
+```plaintext
+is_even : n -> n % 2 = 0;
+classify_number : n ->
+  when (is_even n) is
+    true then "even number"
+    false then "odd number";
+
+even_class : classify_number 4;  /* Returns "even number" ✅ */
+odd_class : classify_number 7;   /* Returns "even number" ❌ Should be "odd number" */
+```
+
+**Root Cause**: In `lang.js`, the wildcard pattern detection uses `if (pattern === true)` which incorrectly matches `false` boolean values as wildcards.
+
+**Location**: `lang.js` in both `evalNode` and `localEvalNodeWithScope` functions.
+
+**Impact**: Affects any boolean pattern matching in `when` expressions.
+
+**Status**: Known issue, requires parser/interpreter fix.
+
+### 2. `and` Operator with Negative Numbers - RESOLVED
+
+**Problem**: The `and` operator requires parentheses for negative numbers due to parser precedence rules.
+
+**Evidence**:
+```plaintext
+/* This fails with "Expected ")" after expression" */
+test_expr : age -> (-5 >= 0) and (-5 <= 120);
+
+/* This works correctly */
+test_expr : age -> ((-5) >= 0) and ((-5) <= 120);
+```
+
+**Root Cause**: This is a **known language feature** documented in `PARSER_PRECEDENCE_FIX.md`. The parser requires explicit parentheses for negative numbers in expressions to avoid precedence ambiguity.
+
+**Solution**: Use parentheses around negative numbers: `((-5) >= 0) and ((-5) <= 120)`
+
+**Status**: ✅ **RESOLVED** - This is expected behavior, not a bug.
+
+### 3. Complex `and` Expressions in Patterns - RESOLVED
+
+**Problem**: Complex `and` expressions in `when` patterns require parentheses for negative numbers.
+
+**Evidence**: The original `tests/21_enhanced_case_statements.txt` failed with:
+```plaintext
+validate_user : name age ->
+  when (name != "") (age >= 0 and age <= 120) is  /* This caused issues */
+    true true then "valid user"
+    ...
+```
+
+**Root Cause**: Same as issue #2 - parentheses required for negative numbers in expressions.
+
+**Solution**: Use parentheses around negative numbers or break into helper functions:
+```plaintext
+/* Option 1: Use parentheses */
+validate_user : name age ->
+  when (name != "") (age >= 0 and age <= 120) is  /* Works if no negative numbers */
+    true true then "valid user"
+    ...
+
+/* Option 2: Break into helper functions (recommended) */
+validate_name : name -> name != "";
+validate_age : age -> age >= 0;
+validate_user : name age ->
+  when (validate_name name) (validate_age age) is  /* This works */
+    true true then "valid user"
+    ...
+```
+
+**Status**: ✅ **RESOLVED** - This is expected behavior, not a bug.
+
+## Suspected Issues
+
+### 4. Parser Precedence in Complex Expressions
+
+**Suspicion**: The parser may have precedence issues with complex expressions in certain contexts.
+
+**Evidence**: Some complex expressions work in isolation but fail when combined with other features.
+
+**Status**: Needs investigation.
+
+### 5. Memory Management in Large Expressions
+
+**Suspicion**: Large or deeply nested expressions might cause memory issues or performance problems.
+
+**Evidence**: No direct evidence, but complex pattern matching could potentially create large ASTs.
+
+**Status**: Needs stress testing.
+
+### 6. Error Handling in Pattern Matching
+
+**Suspicion**: Error handling in pattern matching might not be robust enough for edge cases.
+
+**Evidence**: Some error messages are generic ("No matching pattern found") and don't provide specific debugging information.
+
+**Status**: Needs investigation.
+
+## Areas for Investigation
+
+### 7. Performance with Complex Patterns
+
+**Question**: How does the parser perform with very complex multi-value patterns?
+
+**Investigation Needed**: Stress test with patterns involving many values and complex expressions.
+
+### 8. Edge Cases in Table Access
+
+**Question**: Are there edge cases in table access within `when` expressions that haven't been tested?
+
+**Investigation Needed**: Test with deeply nested tables, missing keys, etc.
+
+### 9. Function Call Complexity Limits
+
+**Question**: Is there a limit to how complex function calls can be in `when` patterns?
+
+**Investigation Needed**: Test with deeply nested function calls, multiple parameters, etc.
+
+### 10. Backward Compatibility Verification
+
+**Question**: Are there any edge cases where the enhanced `when` expressions might break existing code?
+
+**Investigation Needed**: Comprehensive testing of existing test suite with new features.
+
+## Implementation Notes
+
+### Current Workarounds
+
+1. **Boolean Pattern Matching**: Avoid complex boolean patterns until the interpreter bug is fixed.
+2. **Complex `and` Expressions**: Use parentheses around negative numbers or break into helper functions.
+3. **Negative Numbers**: Always use parentheses around negative numbers in expressions: `((-5) >= 0)`.
+
+### Recommended Next Steps
+
+1. **Fix Boolean Pattern Matching**: Address the wildcard/boolean confusion in the interpreter.
+2. **Add Error Diagnostics**: Improve error messages for better debugging.
+3. **Performance Testing**: Stress test with complex patterns.
+4. **Comprehensive Testing**: Verify all edge cases work correctly.
+5. **Documentation**: Update tutorials to mention parentheses requirement for negative numbers.
+
+## Related Files
+
+- `lang.js` - Interpreter implementation (contains boolean pattern matching bug)
+- `parser.js` - Parser implementation (may have precedence issues)
+- `tests/21_enhanced_case_statements.txt` - Test file that exposed several issues
+- `scratch_tests/` - Various test files used for debugging
+
+## Status Summary
+
+| Issue | Severity | Status | Priority |
+|-------|----------|--------|----------|
+| Boolean Pattern Matching | High | Known | High |
+| `and` Operator with Negatives | Low | ✅ Resolved | Low |
+| Complex `and` in Patterns | Low | ✅ Resolved | Low |
+| Parser Precedence | Medium | Suspected | Medium |
+| Memory Management | Low | Suspected | Low |
+| Error Handling | Medium | Suspected | Medium |
+
+**Overall Status**: The language is functional for most use cases, but has some known issues that should be addressed for production use. 
\ No newline at end of file