feat: add spiral plot contours, test infrastructure, and labels description

.claude/agents/agent-test-engineer.md

@@ -1,98 +1,212 @@
 ---
 name: TestEngineer
-description: Domain-specific testing expertise for solar wind physics calculations
+description: Test quality patterns, assertion strength, and coverage enforcement
 priority: medium
 tags:
   - testing
-  - scientific-computing
+  - quality
+  - coverage
 applies_to:
   - tests/**/*.py
-  - solarwindpy/**/*.py
 ---
 
 # TestEngineer Agent
 
 ## Purpose
-Provides domain-specific testing expertise for SolarWindPy's scientific calculations and test design for physics software.
-
-**Use PROACTIVELY for complex physics test design, scientific validation strategies, domain-specific edge cases, and test architecture decisions.**
-
-## Domain-Specific Testing Expertise
-
-### Physics-Aware Software Tests
-- **Thermal equilibrium**: Test mw² = 2kT across temperature ranges and species
-- **Alfvén wave physics**: Test V_A = B/√(μ₀ρ) with proper ion composition
-- **Coulomb collisions**: Test logarithm approximations and collision limits
-- **Instability thresholds**: Test plasma beta and anisotropy boundaries
-- **Conservation laws**: Energy, momentum, mass conservation in transformations
-- **Coordinate systems**: Spacecraft frame transformations and vector operations
-
-### Scientific Edge Cases
-- **Extreme plasma conditions**: n → 0, T → ∞, B → 0 limit behaviors
-- **Degenerate cases**: Single species plasmas, isotropic distributions
-- **Numerical boundaries**: Machine epsilon, overflow/underflow prevention  
-- **Missing data patterns**: Spacecraft data gaps, instrument failure modes
-- **Solar wind events**: Shocks, CMEs, magnetic reconnection signatures
-
-### SolarWindPy-Specific Test Patterns
-- **MultiIndex validation**: ('M', 'C', 'S') structure integrity and access patterns
-- **Time series continuity**: Chronological order, gap interpolation, resampling
-- **Cross-module integration**: Plasma ↔ Spacecraft ↔ Ion coupling validation
-- **Unit consistency**: SI internal representation, display unit conversions
-- **Memory efficiency**: DataFrame views vs copies, large dataset handling
-
-## Test Strategy Guidance
-
-### Scientific Test Design Philosophy
-When designing tests for physics calculations:
-1. **Verify analytical solutions**: Test against known exact results
-2. **Check limiting cases**: High/low beta, temperature, magnetic field limits
-3. **Validate published statistics**: Compare with solar wind mission data
-4. **Test conservation**: Verify invariants through computational transformations
-5. **Cross-validate**: Compare different calculation methods for same quantity
-
-### Critical Test Categories
-- **Physics correctness**: Fundamental equations and relationships
-- **Numerical stability**: Convergence, precision, boundary behavior
-- **Data integrity**: NaN handling, time series consistency, MultiIndex structure
-- **Performance**: Large dataset scaling, memory usage, computation time
-- **Integration**: Cross-module compatibility, spacecraft data coupling
-
-### Regression Prevention Strategy
-- Add specific tests for each discovered physics bug
-- Include parameter ranges from real solar wind missions
-- Test coordinate transformations thoroughly (GSE, GSM, RTN frames)
-- Validate against benchmark datasets from Wind, ACE, PSP missions
-
-## High-Value Test Scenarios
-
-Focus expertise on testing:
-- **Plasma instability calculations**: Complex multi-species physics
-- **Multi-ion interactions**: Coupling terms and drift velocities  
-- **Spacecraft frame transformations**: Coordinate system conversions
-- **Extreme solar wind events**: Shock crossings, flux rope signatures
-- **Numerical fitting algorithms**: Convergence and parameter estimation
-
-## Integration with Domain Agents
-
-Coordinate testing efforts with:
-- **DataFrameArchitect**: Ensure proper MultiIndex structure testing
-- **FitFunctionSpecialist**: Define convergence criteria and fitting validation
-
-Discovers edge cases and numerical stability requirements through comprehensive test coverage (≥95%)
-
-## Test Infrastructure (Automated via Hooks)
-
-**Note**: Routine testing operations are automated via hook system:
+
+Provides expertise in **test quality patterns** and **assertion strength** for SolarWindPy tests.
+Ensures tests verify their claimed behavior, not just "something works."
+
+**Use PROACTIVELY for test auditing, writing high-quality tests, and coverage analysis.**
+
+## Scope
+
+**In Scope**:
+- Test quality patterns and assertion strength
+- Mocking strategies (mock-with-wraps, parameter verification)
+- Coverage enforcement (>=95% requirement)
+- Return type verification patterns
+- Anti-pattern detection and remediation
+
+**Out of Scope**:
+- Physics validation and domain-specific scientific testing
+- Physics formulas, equations, or scientific edge cases
+
+> **Note**: Physics-aware testing will be handled by a future **PhysicsValidator** agent
+> (planned but not yet implemented - requires explicit user approval). Until then,
+> physics validation remains in the codebase itself and automated hooks.
+
+## Test Quality Audit Criteria
+
+When reviewing or writing tests, verify:
+
+1. **Name accuracy**: Does the test name describe what is actually tested?
+2. **Assertion validity**: Do assertions verify the claimed behavior?
+3. **Parameter verification**: Are parameters verified to reach their targets?
+
+## Essential Patterns
+
+### Mock-with-Wraps Pattern
+
+Proves the correct internal method was called while still executing real code:
+
+```python
+with patch.object(instance, "_helper", wraps=instance._helper) as mock:
+    result = instance.method(param=77)
+    mock.assert_called_once()
+    assert mock.call_args.kwargs["param"] == 77
+```
+
+### Three-Layer Assertion Pattern
+
+Every method test should verify:
+1. **Method dispatch** - correct internal path was taken (mock)
+2. **Return type** - `isinstance(result, ExpectedType)`
+3. **Behavior claim** - what the test name promises
+
+### Parameter Passthrough Verification
+
+Use **distinctive non-default values** to prove parameters reach targets:
+
+```python
+# Use 77 (not default 20) to verify parameter wasn't ignored
+instance.method(neighbors=77)
+assert mock.call_args.kwargs["neighbors"] == 77
+```
+
+### Patch Location Rule
+
+Patch where defined, not where imported:
+
+```python
+# GOOD: Patch at definition site
+with patch("module.tools.func", wraps=func):
+    ...
+
+# BAD: Fails if imported locally
+with patch("module.that_uses_it.func"):  # AttributeError
+    ...
+```
+
+## Anti-Patterns to Catch
+
+Flag these weak assertions during review:
+
+- `assert result is not None` - trivially true
+- `assert ax is not None` - axes are always returned
+- `assert len(output) > 0` without type check
+- Using default parameter values (can't distinguish if ignored)
+- Missing `plt.close()` (resource leak)
+- Assertions without error messages
+
+## SolarWindPy Return Types
+
+Common types to verify with `isinstance`:
+
+### Matplotlib
+- `matplotlib.axes.Axes`
+- `matplotlib.colorbar.Colorbar`
+- `matplotlib.contour.QuadContourSet`
+- `matplotlib.contour.ContourSet`
+- `matplotlib.tri.TriContourSet`
+- `matplotlib.text.Text`
+
+### Pandas
+- `pandas.DataFrame`
+- `pandas.Series`
+- `pandas.MultiIndex` (M/C/S structure)
+
+## Coverage Requirements
+
+- **Minimum**: 95% coverage required
+- **Enforcement**: Pre-commit hooks in `.claude/hooks/`
+- **Reports**: `pytest --cov=solarwindpy --cov-report=html`
+
+## Integration vs Unit Tests
+
+### Unit Tests
+- Test single method/function in isolation
+- Use mocks to verify internal behavior
+- Fast execution
+
+### Integration Tests (Smoke Tests)
+- Loop through variants to verify all paths execute
+- Don't need detailed mocking
+- Catch configuration/wiring issues
+
+```python
+def test_all_methods_work(self):
+    """Smoke test: all methods run without error."""
+    for method in ["rbf", "grid", "tricontour"]:
+        result = instance.method(method=method)
+        assert len(result) > 0, f"{method} failed"
+```
+
+## Test Infrastructure (Automated)
+
+Routine testing operations are automated via hooks:
 - Coverage enforcement: `.claude/hooks/pre-commit-tests.sh`
-- Test execution: `.claude/hooks/test-runner.sh`  
+- Test execution: `.claude/hooks/test-runner.sh`
 - Coverage monitoring: `.claude/hooks/coverage-monitor.py`
-- Test scaffolding: `.claude/scripts/generate-test.py`
-
-Focus agent expertise on:
-- Complex test scenario design
-- Physics-specific validation strategies
-- Domain knowledge for edge case identification
-- Integration testing between scientific modules
 
-Use this focused expertise to ensure SolarWindPy maintains scientific integrity through comprehensive, physics-aware testing that goes beyond generic software testing patterns.
+## ast-grep Anti-Pattern Detection
+
+Use ast-grep MCP tools for automated structural code analysis:
+
+### Available MCP Tools
+- `mcp__ast-grep__find_code` - Simple pattern searches
+- `mcp__ast-grep__find_code_by_rule` - Complex YAML rules with constraints
+- `mcp__ast-grep__test_match_code_rule` - Test rules before deployment
+
+### Key Detection Rules
+
+**Trivial assertions:**
+```yaml
+id: trivial-assertion
+language: python
+rule:
+  pattern: assert $X is not None
+```
+
+**Mocks missing wraps:**
+```yaml
+id: mock-without-wraps
+language: python
+rule:
+  pattern: patch.object($INSTANCE, $METHOD)
+  not:
+    has:
+      pattern: wraps=$_
+```
+
+**Good mock pattern (track improvement):**
+```yaml
+id: mock-with-wraps
+language: python
+rule:
+  pattern: patch.object($INSTANCE, $METHOD, wraps=$WRAPPED)
+```
+
+### Audit Workflow
+
+1. **Detect:** Run ast-grep rules to find anti-patterns
+2. **Review:** Examine flagged locations for false positives
+3. **Fix:** Apply patterns from TEST_PATTERNS.md
+4. **Verify:** Re-run detection to confirm fixes
+
+**Current codebase state (as of audit):**
+- 133 `assert X is not None` (potential trivial assertions)
+- 76 `patch.object` without `wraps=` (weak mocks)
+- 4 `patch.object` with `wraps=` (good pattern)
+
+## Documentation Reference
+
+For comprehensive patterns with code examples, see:
+**`.claude/docs/TEST_PATTERNS.md`**
+
+Contains:
+- 16 established patterns with examples
+- 8 anti-patterns to avoid
+- Real examples from TestSpiralPlot2DContours
+- SolarWindPy-specific type reference
+- ast-grep YAML rules for automated detection

.claude/commands/swp/dev/dataframe-audit.md

@@ -73,26 +73,60 @@ df.loc[:, ~df.columns.duplicated()]
 
 ### Audit Execution
 
-**Primary Method: ast-grep (recommended)**
+**PRIMARY: ast-grep MCP Tools (No Installation Required)**
 
-ast-grep provides structural pattern matching for more accurate detection:
+Use these MCP tools for structural pattern matching:
 
-```bash
-# Install ast-grep if not available
-# macOS: brew install ast-grep
-# pip: pip install ast-grep-py
-# cargo: cargo install ast-grep
+```python
+# 1. Boolean indexing anti-pattern (swp-df-001)
+mcp__ast-grep__find_code(
+    project_folder="/path/to/SolarWindPy",
+    pattern="get_level_values($LEVEL)",
+    language="python",
+    max_results=50
+)
+
+# 2. reorder_levels usage - check for missing sort_index (swp-df-002)
+mcp__ast-grep__find_code(
+    project_folder="/path/to/SolarWindPy",
+    pattern="reorder_levels($LEVELS)",
+    language="python",
+    max_results=30
+)
+
+# 3. Deprecated level= aggregation (swp-df-003) - pandas 2.0+
+mcp__ast-grep__find_code(
+    project_folder="/path/to/SolarWindPy",
+    pattern="$METHOD(axis=1, level=$L)",
+    language="python",
+    max_results=30
+)
+
+# 4. Good .xs() usage - track adoption
+mcp__ast-grep__find_code(
+    project_folder="/path/to/SolarWindPy",
+    pattern="$DF.xs($KEY, axis=1, level=$L)",
+    language="python"
+)
+
+# 5. pd.concat without duplicate check (swp-df-005)
+mcp__ast-grep__find_code(
+    project_folder="/path/to/SolarWindPy",
+    pattern="pd.concat($ARGS)",
+    language="python",
+    max_results=50
+)
+```
 
-# Run full audit with all DataFrame rules
-sg scan --config tools/dev/ast_grep/dataframe-patterns.yml solarwindpy/
+**FALLBACK: CLI ast-grep (requires local `sg` installation)**
 
-# Run specific rule only
-sg scan --config tools/dev/ast_grep/dataframe-patterns.yml --rule swp-df-003 solarwindpy/
+```bash
+# Quick pattern search (if sg installed)
+sg run -p "get_level_values" -l python solarwindpy/
+sg run -p "reorder_levels" -l python solarwindpy/
 ```
 
-**Fallback Method: grep (if ast-grep unavailable)**
-
-If ast-grep is not installed, use grep for basic pattern detection:
+**FALLBACK: grep (always available)**
 
 ```bash
 # .xs() usage (informational)

.claude/commands/swp/dev/fix-tests.md → .claude/commands/swp/dev/diagnose-test-failures.md

@@ -2,7 +2,7 @@
 description: Diagnose and fix failing tests with guided recovery
 ---
 
-## Fix Tests Workflow: $ARGUMENTS
+## Diagnose Test Failures: $ARGUMENTS
 
 ### Phase 1: Test Execution & Analysis