docs(feature-integration): replace incorrect formula refs with units architecture

Remove all thermal speed formula (mw²=2kT) enforcement from feature integration
documentation. Replace with accurate units architecture documentation reflecting
SolarWindPy's actual implementation pattern.

Changes:
- Document three-tier units system (storage/display/calculation)
- Emphasize bidirectional conversion pattern (display→SI→display)
- Correct temperature display units to 10⁵ K
- Update validation checklists to check self.units.* conversion
- Replace formula-specific constraints with general vector magnitude rules
- Remove curve fitting example (distraction from core units pattern)

Files updated (9):
- 01_memory_hierarchy.md: Rewrote physics constants section
- 02_skills_system.md: Updated physics-validator skill validation
- 03_subagents.md: Removed formula enforcement, added units validation
- 06_output_styles.md: Changed physics-focused style emphasis
- 07_slash_commands.md: Updated /physics and /review checklists
- 08_plugin_packaging.md: Updated skill description
- INDEX.md: Updated workflow example
- appendices/plugin_quick_start.md: Updated skill template
- appendices/quick_reference.md: Updated command description

Validates zero thermal speed formula references remain (grep verified).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: blalterman

.claude/docs/feature_integration/01_memory_hierarchy.md

@@ -223,37 +223,50 @@ Enhanced: CLAUDE.md (orchestrator with imports)
 **File:** `.claude/memory/physics-constants.md`
 
 ```markdown
-# Solar Wind Physics Constants & Formulas
+# Solar Wind Physics: Units Architecture
 
-## Critical Formulas
+## Units System
 
-### Thermal Speed
-**CORRECT:** `mw² = 2kT`
-**INCORRECT:** `mw² = 3kT` ❌
+### Storage Units (Instrument Measurements)
+SolarWindPy stores only directly measured quantities:
+- **n:** Number density [cm⁻³]
+- **v:** Velocity [km/s]
+- **w:** Thermal speed [km/s]
 
-Where:
-- `m` = particle mass (kg)
-- `w` = thermal speed (m/s)
-- `k` = Boltzmann constant (1.380649 × 10⁻²³ J/K)
-- `T` = temperature (K)
+### Display Units (All Quantities)
+All quantities displayed in units defined by `solarwindpy.core.units_constants.Units`:
+- Density: cm⁻³ (`self.units.n = 1e6`)
+- Velocity/speeds: km/s (`self.units.v = 1e3`)
+- Temperature: 10⁵ K (`self.units.temperature = 1e5`)
+- Magnetic field: nT (`self.units.bfield = 1e-9`)
+- Thermal pressure: pPa (`self.units.pth = 1e-12`)
+- See `Units` class for complete list
 
-### Alfvén Speed
-```
-v_A = B / √(μ₀ρ)
-```
-- `B` = magnetic field strength (T)
-- `μ₀` = permeability of free space (4π × 10⁻⁷ H/m)
-- `ρ` = mass density (kg/m³)
+### Calculation Units (SI)
+All physics calculations performed in SI units via conversion factors.
+
+## Units Conversion Pattern (Display → SI → Display)
+
+**CRITICAL:** All calculations must convert units bidirectionally.
 
-## SI Units (MANDATORY)
+```python
+# Example from ions.py temperature property (line 222-224)
+def temperature(self):
+    # Input conversion: display → SI
+    w = self.w.data * self.units.w              # km/s → m/s
+
+    # Calculate in SI
+    coeff = 0.5 * m / (self.constants.kb.J * self.units.temperature)
+    temp = coeff * w.pow(2)
+
+    # Output: Result automatically in display units (10⁵ K) via coeff
+    return temp
+```
 
-| Quantity | Unit | Symbol |
-|----------|------|--------|
-| Velocity | meters/second | m/s |
-| Density | per cubic meter | m⁻³ |
-| Temperature | Kelvin | K |
-| Magnetic Field | Tesla | T |
-| Energy | Joules | J |
+**Pattern to validate:**
+1. Input: `quantity * self.units.<name>` (display → SI)
+2. Calculate: Perform physics calculation in SI
+3. Output: `result / self.units.<name>` (SI → display)
 
 ## Missing Data Convention
 **ALWAYS use NaN** for missing/invalid data.
@@ -272,10 +285,11 @@ velocity_missing = 0     # NO!
 
 ## Physical Constraints
 
-- ✅ Density > 0 (particles/m³)
-- ✅ Temperature > 0 (K)
-- ✅ Speed ≥ 0 (m/s)
-- ✅ Thermal speed uses factor of 2, not 3
+- ✅ Density > 0 (n > 0 in cm⁻³)
+- ✅ Temperature > 0 (T > 0 in 10⁵ K)
+- ✅ Thermal speed ≥ 0 (w ≥ 0 in km/s, always positive scalar)
+- ✅ Vector magnitudes ≥ 0 (e.g., |v|, |B|), though components may be negative
+- ✅ Physical constants from `solarwindpy.core.units_constants.Constants`
 ```
 
 ##### Memory File 2: DataFrame Patterns
@@ -419,16 +433,14 @@ class TestClassName:
         result_large = function(np.random.rand(10000))
         assert len(result_large) == 10000
 
-    def test_function_physics_validation(self):
-        """Validate physics correctness (REQUIRED for scientific functions)."""
-        # Thermal speed formula check
-        ion = Ion(temperature=1e5, mass=1.67e-27)
-        thermal_speed = ion.thermal_speed()
+    def test_function_units_conversion(self):
+        """Validate units conversion pattern (REQUIRED for calculation methods)."""
+        # Check that calculations use units conversion
+        import inspect
+        source = inspect.getsource(ion.temperature.fget)
 
-        # Verify mw² = 2kT
-        k_B = 1.380649e-23
-        expected = np.sqrt(2 * k_B * 1e5 / 1.67e-27)
-        np.testing.assert_allclose(thermal_speed, expected, rtol=1e-6)
+        # Should contain self.units.w for input conversion (display → SI)
+        assert 'self.units.w' in source, "Missing units conversion in calculation"
 
     def test_function_error_handling(self):
         """Test invalid inputs raise appropriate errors (REQUIRED)."""
@@ -551,7 +563,7 @@ This file provides essential guidance to Claude Code when working with the Solar
 **What Goes in Project Memory:**
 All SolarWindPy-specific conventions, rules, and knowledge that should be consistent across all team members:
 
-- **Physics constants and formulas** (thermal speed, Alfvén speed, etc.)
+- **Units architecture** (storage vs display units, conversion patterns)
 - **MultiIndex structure** (M/C/S levels, capitalization rules)
 - **Testing requirements** (≥95% coverage, physics validation patterns)
 - **DataFrame patterns** (efficient access with .xs(), avoiding SettingWithCopyWarning)
@@ -797,7 +809,7 @@ All SolarWindPy-specific conventions, rules, and knowledge that should be consis
 **Measurement Methodology:**
 
 *How Time Savings Are Calculated:*
-1. **Baseline measurement:** Track time spent repeating context ("remember to use SI units," "check thermal speed formula") in 20 representative sessions
+1. **Baseline measurement:** Track time spent repeating context ("remember units conversion pattern," "check display→SI→display") in 20 representative sessions
 2. **Average repetition time:** 5-10 minutes per session for context-setting
 3. **Session frequency:** Estimate 10-15 development sessions per week based on team activity
 4. **Calculation:** (5-10 min/session) × (10-15 sessions/week) = 50-150 min/week saved
@@ -828,10 +840,10 @@ grep "@.claude/memory" /tmp/memory_check.txt
 
 #### Test 2: Context Preservation
 ```
-Session 1: Ask about thermal speed formula
+Session 1: Ask about units conversion pattern
 Session 2 (new): Ask same question without repeating context
-Expected: Claude knows thermal speed is mw²=2kT from memory
-Validation: No need to re-explain physics rules
+Expected: Claude knows display→SI→display pattern from memory
+Validation: No need to re-explain units architecture
 ```
 
 #### Test 3: Selective Loading

.claude/docs/feature_integration/02_skills_system.md

@@ -48,8 +48,8 @@ Skills are model-invoked capability packages that Claude autonomously activates
 **Pain Points Addressed:**
 
 ✅ **Agent Coordination Overhead (HIGH IMPACT)**
-*Current state:* Manual agent selection via Task tool requires explicit prompts like "Use PhysicsValidator to verify thermal speed calculations"
-*With Skills:* Automatic activation when user requests physics validation, thermal speed checks, or unit verification
+*Current state:* Manual agent selection via Task tool requires explicit prompts like "Use PhysicsValidator to verify units conversion patterns"
+*With Skills:* Automatic activation when user requests physics validation, units pattern checks, or unit verification
 *Reduction:* 40-60% decrease in explicit agent invocation overhead
 
 ✅ **Repetitive Task Automation (HIGH IMPACT)**
@@ -205,7 +205,7 @@ User Request → Skill Auto-Detection → [Skill OR Task Agent] → Result
 ```yaml
 ---
 name: physics-validator
-description: Automatically validates solar wind physics calculations including thermal speed (mw²=2kT), SI unit consistency, proper NaN handling for missing data, and physical constraint verification. Activates when user mentions physics validation, unit checking, thermal speed, or scientific correctness.
+description: Automatically validates solar wind physics calculations focusing on units conversion patterns, proper NaN handling for missing data, and physical constraint verification. Verifies calculations use self.units.* for SI conversion (display units → SI → display units). Activates when user mentions physics validation, unit checking, or scientific correctness.
 allowed-tools: [Read, Grep, Bash(python .claude/hooks/physics-validation.py*)]
 ---
 
@@ -216,17 +216,21 @@ Ensures all physics calculations in SolarWindPy maintain scientific correctness.
 
 ## Automatic Activation Triggers
 - "validate physics"
-- "check thermal speed"
-- "verify units"
+- "verify units conversion"
+- "check units pattern"
 - "ensure SI units"
 - "physics correctness"
 - Code changes to `solarwindpy/core/ion.py` or `solarwindpy/core/plasma.py`
 
 ## Validation Checklist
-1. **Thermal Speed Formula:** mw² = 2kT (not 3kT)
-2. **SI Units:** velocity (m/s), density (m⁻³), temperature (K)
-3. **NaN Handling:** Missing data as NaN, never 0 or -999
-4. **Physical Constraints:** Positive densities, temperatures, speeds
+1. **Units Conversion Pattern:** Calculations must use `quantity * self.units.<name>` for SI conversion
+   - Storage units: cm⁻³ (density), km/s (velocity, thermal speed)
+   - Display units: All quantities per `Units` class (see `solarwindpy.core.units_constants`)
+   - Calculation units: m⁻³, m/s, K (SI)
+   - Example: `w = self.w.data * self.units.w` before `w.pow(2)` (ions.py:222)
+   - Check BOTH input conversion (display→SI) AND output conversion (SI→display)
+2. **NaN Handling:** Missing data as NaN, never 0 or -999
+3. **Physical Constraints:** Positive densities, temperatures, thermal speeds (scalars ≥ 0; velocity components may be negative)
 
 ## Execution Pattern
 ```bash
@@ -369,7 +373,7 @@ def test_function_name_happy_path():
 def test_function_name_physics():
     """Validate physics correctness."""
     # Physics-specific assertions
-    assert thermal_speed_formula_check(result)
+    assert units_conversion_pattern_check(result)
 ```
 
 ## Integration with TestEngineer Agent
@@ -789,7 +793,7 @@ Validation: Complex multi-step tasks should still use agents
 
 #### Test 4: Auto-activation on File Changes
 ```
-Scenario: Edit solarwindpy/core/ion.py (thermal speed calculation)
+Scenario: Edit solarwindpy/core/ion.py (physics calculation method)
 Expected: physics-validator skill triggers post-edit
 Validation: Verify physics validation report generated
 ```

.claude/docs/feature_integration/03_subagents.md

@@ -91,7 +91,7 @@ Decision Tree:
     └── Use Subagent (independent context, deep expertise)
 
 Examples:
-- "Validate thermal speed formula" → Skill (physics-validator)
+- "Verify units conversion pattern" → Skill (physics-validator)
 - "Check physics correctness in ion.py" → Task (PhysicsValidator)
 - "Refactor entire Plasma class for better memory efficiency, analyze trade-offs" → Subagent (dataframe-architect)
 ```
@@ -233,7 +233,7 @@ Examples:
 ```yaml
 ---
 name: physics-validator
-description: Deep physics analysis specialist for solar wind calculations. Validates thermal speed formulas, unit consistency, physical constraints, and scientific correctness across multiple files.
+description: Deep physics analysis specialist for solar wind calculations. Validates units conversion patterns, physical constraints, and scientific correctness across multiple files.
 tools: [Read, Grep, Bash(python .claude/hooks/physics-validation.py*), Bash(pytest*)]
 model: sonnet
 ---
@@ -244,38 +244,38 @@ You are a solar wind physics expert specializing in validating scientific correc
 
 ## Core Responsibilities
 
-1. **Formula Validation**
-   - Thermal speed: mw² = 2kT (NOT 3kT)
-   - Alfvén speed: v_A = B / √(μ₀ρ)
-   - Plasma frequency: ωₚ = √(nₑe²/(ε₀mₑ))
-
-2. **Unit Consistency (SI Units MANDATORY)**
-   - Velocity: m/s
-   - Density: m⁻³
-   - Temperature: K
-   - Magnetic Field: T
-
-3. **Physical Constraints**
-   - All densities, temperatures, speeds > 0
+1. **Units Conversion Validation**
+   - Verify calculations use `self.units.*` for SI conversion
+   - Storage units: cm⁻³ (density), km/s (velocity, thermal speed)
+   - Display units: All quantities per `Units` class (see `solarwindpy.core.units_constants`)
+   - Calculation units: m⁻³ (density), m/s (velocity, thermal speed), K (temperature) - SI
+   - Flag calculations using raw data without unit conversion (input)
+   - Flag calculations returning SI results without converting to display units (output)
+   - Example pattern: `w = self.w.data * self.units.w` → calculate → `result / self.units.output`
+
+2. **Physical Constraints**
+   - Density > 0 (n > 0 in cm⁻³)
+   - Temperature > 0 (T > 0 in 10⁵ K)
+   - Thermal speed ≥ 0 (w ≥ 0 in km/s, always positive scalar)
+   - Vector magnitudes ≥ 0 (e.g., |v|, |B|), though vector components may be negative
    - NaN for missing data (NEVER 0, -999, or sentinels)
-   - Proton mass: 1.6726219 × 10⁻²⁷ kg
-   - Boltzmann constant: 1.380649 × 10⁻²³ J/K
+   - Physical constants from `solarwindpy.core.units_constants.Constants`
 
-4. **Multi-file Analysis**
-   - Cross-reference formulas across modules
-   - Identify inconsistencies in physics implementations
-   - Suggest refactoring for scientific accuracy
+3. **Multi-file Analysis**
+   - Cross-reference units patterns across modules
+   - Identify inconsistencies in units conversion implementations
+   - Suggest refactoring for architectural consistency
 
 ## Validation Process
 
 1. Read target files using Read tool
-2. Search for physics formulas using Grep
-3. Validate against canonical formulas (above)
+2. Search for units conversion patterns using Grep
+3. Validate units conversion patterns (display→SI→display)
 4. Run physics validation script: `python .claude/hooks/physics-validation.py`
 5. Report findings with:
    - ✅ Correct implementations
-   - ⚠️ Warnings (potential issues)
-   - ❌ Errors (must fix)
+   - ⚠️ Warnings (potential issues - missing conversions)
+   - ❌ Errors (must fix - raw data used in calculations)
    - 💡 Recommendations
 
 ## Output Format
@@ -657,32 +657,6 @@ print(f"b = {b_fit:.3f} ± {b_err:.3f}")
 print(f"R² = {r_squared:.3f}")
 ```
 
-### Physics-Based Model Fitting
-```python
-def thermal_speed_model(T, mass):
-    """Thermal speed: w = √(2kT/m)"""
-    k_B = 1.380649e-23  # J/K
-    return np.sqrt(2 * k_B * T / mass)
-
-# Fit thermal speed data to extract mass
-def fit_func(T, mass):
-    return thermal_speed_model(T, mass)
-
-mass_fit, mass_cov = curve_fit(
-    fit_func,
-    temperatures,
-    measured_speeds,
-    bounds=(0, np.inf)  # Mass must be positive
-)
-
-mass_err = np.sqrt(mass_cov[0, 0])
-print(f"Fitted mass: {mass_fit[0]:.3e} ± {mass_err:.3e} kg")
-
-# Compare to known proton mass
-proton_mass = 1.6726219e-27  # kg
-print(f"Difference from proton mass: {abs(mass_fit[0] - proton_mass) / proton_mass * 100:.1f}%")
-```
-
 ## Output Format
 
 Provide complete analysis including:
@@ -702,14 +676,14 @@ Provide complete analysis including:
 
 **Automatic Invocation** (Claude decides based on description):
 ```
-User: "I need a comprehensive analysis of thermal speed calculations across all ion classes, checking for formula consistency and proposing refactoring if needed."
+User: "I need a comprehensive analysis of units conversion patterns across all ion classes, checking for consistency and proposing refactoring if needed."
 
-Claude: [Automatically invokes physics-validator subagent due to "comprehensive analysis" + "thermal speed" + "formula consistency"]
+Claude: [Automatically invokes physics-validator subagent due to "comprehensive analysis" + "units conversion" + "consistency"]
 ```
 
 **Explicit Invocation:**
 ```
-User: "Use the physics-validator subagent to analyze ion.py for thermal speed correctness."
+User: "Use the physics-validator subagent to analyze ion.py for units conversion correctness."
 
 Claude: [Explicitly invokes physics-validator subagent]
 ```