initial commit

_bmad-output/implementation-artifacts/2-6-custom-user-defined-units.md

@@ -0,0 +1,45 @@
+---
+epic: 2
+story: 2.6
+title: "Custom User-Defined Units"
+status: draft
+---
+
+## Epic 2 — Unit Conversion System
+**Goal:** Support 200+ units across all major categories with SI prefix support.
+
+### Story 2.6: Custom User-Defined Units
+
+As a CalcPad user,
+I want to define my own units such as `1 sprint = 2 weeks` or `1 story_point = 4 hours`,
+So that I can use domain-specific units in my calculations.
+
+**Acceptance Criteria:**
+
+**Given** the user writes `1 sprint = 2 weeks` on a line
+**When** the engine evaluates the sheet
+**Then** it registers `sprint` as a custom unit convertible to and from `weeks`
+**And** subsequent lines can use `sprint` in expressions
+
+**Given** a custom unit `1 sprint = 2 weeks` is defined
+**When** the expression `3 sprints in days` is evaluated
+**Then** the result is `42 days`
+
+**Given** a custom unit `1 story_point = 4 hours` is defined
+**When** the expression `10 story_points in hours` is evaluated
+**Then** the result is `40 hours`
+
+**Given** a custom unit is defined in one sheet
+**When** the user configures it as a global custom unit
+**Then** it is available in all sheets
+**And** sheet-local definitions override global ones if there is a name conflict
+
+**Given** a custom unit definition that creates a circular dependency (e.g., `1 foo = 2 bar` and `1 bar = 3 foo`)
+**When** the engine processes these definitions
+**Then** it detects the circular dependency and returns an error
+**And** it does not enter an infinite loop
+
+**Given** a custom unit name that conflicts with a built-in unit name
+**When** the user defines it
+**Then** the engine warns that the built-in unit is being shadowed
+**And** the custom definition takes precedence within that sheet