1 files changed, 164 insertions, 0 deletions
diff --git a/js/scripting-lang/design/NEGATIVE_NUMBER_HANDLING.md b/js/scripting-lang/design/NEGATIVE_NUMBER_HANDLING.md
new file mode 100644
index 0000000..c36d838
--- /dev/null
+++ b/js/scripting-lang/design/NEGATIVE_NUMBER_HANDLING.md
@@ -0,0 +1,164 @@
+# Negative Number Handling
+
+## Overview
+
+This document describes how negative numbers are handled in the scripting language, including the parser precedence rules and best practices for working with negative values.
+
+## The Core Rule
+
+**Negative numbers always require parentheses in expressions.**
+
+This is a fundamental language feature, not a bug. The parser requires explicit parentheses around negative numbers to avoid precedence ambiguity.
+
+## Why This Exists
+
+The parser needs to distinguish between two different uses of the `-` symbol:
+
+1. **Unary minus** (negative numbers): `-5`
+2. **Binary minus** (subtraction): `5 - 3`
+
+Without parentheses, expressions like `-5 + 3` are ambiguous and cause parsing errors.
+
+## Examples
+
+### ❌ Incorrect Usage
+
+```plaintext
+/* These will cause parsing errors */
+result1 : -5 + 3;
+result2 : -5 >= 0;
+result3 : f -5;
+result4 : -5 * 2;
+result5 : (-5 >= 0) and (-5 <= 120);
+```
+
+### ✅ Correct Usage
+
+```plaintext
+/* These work correctly */
+result1 : (-5) + 3;
+result2 : (-5) >= 0;
+result3 : f (-5);
+result4 : (-5) * 2;
+result5 : ((-5) >= 0) and ((-5) <= 120);
+```
+
+## Common Patterns
+
+### Function Calls
+
+```plaintext
+/* Function calls with negative numbers */
+double : x -> x * 2;
+result : double (-5);  /* ✅ Correct */
+
+/* Higher-order functions */
+numbers : {-3, -2, -1, 0, 1, 2, 3};
+abs_values : map (x -> if x < 0 then (-x) else x) numbers;
+```
+
+### Comparisons
+
+```plaintext
+/* Comparisons with negative numbers */
+is_negative : x -> x < 0;
+test1 : is_negative (-5);  /* ✅ Correct */
+
+/* Range validation */
+validate_age : age -> (age >= 0) and (age <= 120);
+test2 : validate_age (-5);  /* ✅ Correct */
+```
+
+### Arithmetic Operations
+
+```plaintext
+/* Basic arithmetic */
+sum : (-5) + 3;        /* ✅ Correct */
+product : (-5) * 2;    /* ✅ Correct */
+difference : 10 - (-5); /* ✅ Correct (binary minus) */
+```
+
+### Logical Expressions
+
+```plaintext
+/* Complex boolean logic */
+complex_check : x -> ((-5) >= 0) and ((-5) <= 120);  /* ✅ Correct */
+
+/* Step-by-step approach (recommended) */
+step1 : (-5) >= 0;     /* false */
+step2 : (-5) <= 120;   /* true */
+result : step1 and step2;  /* false */
+```
+
+### Pattern Matching
+
+```plaintext
+/* Pattern matching with negative numbers */
+classify : x ->
+  when x is
+    (-5) then "negative five"
+    0 then "zero"
+    5 then "positive five"
+    _ then "other";
+```
+
+## Best Practices
+
+### 1. Always Use Parentheses
+
+When in doubt, add parentheses around negative numbers. It's better to be explicit than to encounter parsing errors.
+
+### 2. Break Complex Expressions
+
+For complex expressions involving negative numbers, consider breaking them into smaller steps:
+
+```plaintext
+/* Instead of this complex expression */
+complex : ((-5) >= 0) and ((-5) <= 120) and ((-5) != 0);
+
+/* Do this */
+step1 : (-5) >= 0;
+step2 : (-5) <= 120;
+step3 : (-5) != 0;
+result : step1 and step2 and step3;
+```
+
+### 3. Use Helper Functions
+
+Create helper functions for common operations involving negative numbers:
+
+```plaintext
+/* Helper functions for validation */
+is_positive : x -> x > 0;
+is_negative : x -> x < 0;
+is_zero : x -> x = 0;
+
+/* Use them in complex expressions */
+validate_input : x -> (is_positive x) or (is_negative x) or (is_zero x);
+```
+
+## Error Messages
+
+When you forget parentheses, you'll see errors like:
+
+- `"Expected ")" after expression"`
+- `"Unexpected token in parsePrimary: PLUS"`
+- `"Unexpected token in parsePrimary: GREATER_EQUAL"`
+
+These errors indicate that the parser encountered an operator after a negative number without proper parentheses.
+
+## Historical Context
+
+This behavior was documented in the `PARSER_PRECEDENCE_FIX.md` file as part of the language's design. Rather than implementing complex precedence handling that could lead to logic loops, the language requires explicit parentheses for clarity and consistency.
+
+## Related Documentation
+
+- [Juxtaposition Tutorial](tutorials/01_Juxtaposition_Function_Application.md#negative-numbers-and-parentheses) - Detailed examples and patterns
+- [Introduction Tutorial](tutorials/00_Introduction.md) - Basic overview
+- [Parser Precedence Fix](design/HISTORY/PARSER_PRECEDENCE_FIX.md) - Historical context
+
+## Summary
+
+**Remember**: Negative numbers require parentheses in all expressions. This is a language feature designed for clarity and consistency, not a limitation to be worked around.
+
+**Rule of thumb**: When you see a negative number in an expression, wrap it in parentheses: `(-5)` instead of `-5`. 
\ No newline at end of file