Merge branch 'master' of github.com:blalterman/SolarWindPy

Author: blalterman

.claude/compacted_state.md

@@ -7,26 +7,25 @@
 
 - **Pre-Compaction Context**: ~8,491 tokens (1,799 lines)
 - **Target Compression**: medium (35% reduction)
-- **Target Tokens**: ~5,519 tokens
+- **Target Tokens**: ~5,567 tokens
 - **Strategy**: medium compression with prose focus
 
 ## Content Analysis
 - **Files Analyzed**: 9
 - **Content Breakdown**: 
-  - Code: 426 lines
-  - Prose: 422 lines  
+  - Code: 429 lines
+  - Prose: 425 lines  
   - Tables: 0 lines
-  - Lists: 393 lines
+  - Lists: 395 lines
   - Headers: 222 lines
 - **Token Estimates**:
-  - Line-based: 5,397
-  - Character-based: 15,109
-  - Word-based: 9,359
-  - Content-weighted: 4,099
-  - **Final estimate**: 8,491 tokens
+  - Line-based: 5,424
+  - Character-based: 15,265
+  - Word-based: 9,449
+  - Content-weighted: 4,123
+  - **Final estimate**: 8,565 tokens
 
 ## Git State
-
 ### Current Branch: plan/pr-270-doc-validation-fixes
 ### Last Commit: dbe38f3 - refactor: right-size documentation validation framework (blalterman, 35 seconds ago)
 
@@ -134,7 +133,7 @@ conda info --envs  # Check active environment
 - [ ] **Changes**: Review uncommitted changes
 
 ### 📊 Efficiency Metrics
-- **Context Reduction**: 35.0% (8,491 → 5,519 tokens)
+- **Context Reduction**: 35.0% (8,565 → 5,567 tokens)
 - **Estimated Session Extension**: 21 additional minutes of productive work
 - **Compaction Strategy**: medium compression focused on prose optimization
 

.claude/hooks/plan-completion-manager.py

@@ -7,6 +7,7 @@
 import os
 import json
 import shutil
+import re
 from pathlib import Path
 from datetime import datetime
 import subprocess
@@ -96,6 +97,81 @@ def move_plan_to_completed(plan_name: str, source_dir: Path, completed_dir: Path
         return False
 
 
+def generate_closeout_documentation(plan_name: str, plan_dir: Path) -> bool:
+    """
+    Generate closeout documentation for a completed plan.
+    
+    Args:
+        plan_name: Name of the plan
+        plan_dir: Path to the plan directory
+        
+    Returns:
+        True if closeout generation was successful
+    """
+    try:
+        # Read the overview file to extract metadata
+        overview_file = plan_dir / "0-Overview.md"
+        if not overview_file.exists():
+            print(f"⚠️  No overview file found for {plan_name}")
+            return False
+        
+        with open(overview_file, 'r') as f:
+            overview_content = f.read()
+        
+        # Extract key metadata
+        estimated_duration = extract_metadata(overview_content, "Estimated Duration")
+        total_phases = extract_metadata(overview_content, "Total Phases")
+        objective = extract_section(overview_content, "🎯 Objective")
+        
+        # Load template
+        template_file = Path('plans/closeout-template.md')
+        if not template_file.exists():
+            print(f"⚠️  Closeout template not found: {template_file}")
+            return False
+        
+        with open(template_file, 'r') as f:
+            template_content = f.read()
+        
+        # Replace template placeholders
+        closeout_content = template_content.replace('[Plan Name]', plan_name)
+        closeout_content = closeout_content.replace('[Plan Name from 0-Overview.md]', plan_name)
+        closeout_content = closeout_content.replace('[YYYY-MM-DD]', datetime.now().strftime('%Y-%m-%d'))
+        closeout_content = closeout_content.replace('[estimated hours]', estimated_duration or 'N/A')
+        closeout_content = closeout_content.replace('[N]/[N]', f"{total_phases}/{total_phases}" if total_phases else 'N/A')
+        closeout_content = closeout_content.replace('[feature/plan-name]', f'feature/{plan_name}')
+        closeout_content = closeout_content.replace('[plan/plan-name]', f'plan/{plan_name}')
+        closeout_content = closeout_content.replace('[plan-name]', plan_name)
+        
+        if objective:
+            closeout_content = closeout_content.replace('[Restate main objective from 0-Overview.md]', objective.strip())
+        
+        # Create closeout file
+        closeout_file = plan_dir / "9-Closeout.md"
+        with open(closeout_file, 'w') as f:
+            f.write(closeout_content)
+        
+        print(f"✅ Generated closeout documentation: {closeout_file}")
+        return True
+        
+    except Exception as e:
+        print(f"❌ Error generating closeout for {plan_name}: {e}")
+        return False
+
+
+def extract_metadata(content: str, field: str) -> str:
+    """Extract metadata field from plan content."""
+    pattern = rf"- \*\*{field}\*\*: (.+)"
+    match = re.search(pattern, content)
+    return match.group(1).strip() if match else ""
+
+
+def extract_section(content: str, header: str) -> str:
+    """Extract section content from plan."""
+    pattern = rf"## {re.escape(header)}\n(.+?)(?=\n## |\n---|\Z)"
+    match = re.search(pattern, content, re.DOTALL)
+    return match.group(1).strip() if match else ""
+
+
 def preserve_plan_branches(plan_name: str) -> dict:
     """
     Ensure plan branches are preserved and not deleted.
@@ -173,6 +249,11 @@ def scan_and_archive_completed_plans():
             if is_plan_completed(item):
                 print(f"✅ Plan completed: {item.name}")
 
+                # Generate closeout documentation
+                closeout_success = generate_closeout_documentation(item.name, item)
+                if not closeout_success:
+                    print(f"⚠️  Proceeding with archival despite closeout generation issues")
+                
                 # Preserve branches before moving
                 branch_status = preserve_plan_branches(item.name)
                 preserved_branches.append(branch_status)

plans/0-overview-template.md

@@ -32,6 +32,113 @@ N. [N-Final-Phase.md](./N-Final-Phase.md)
 ## 🧠 Context
 [Background information, motivation, and relevant links]
 
+## 📈 Plan Propositions
+
+### Risk Proposition
+**Technical Risks**:
+- [Breaking changes, compatibility issues, complexity factors]
+- [Dependencies on external libraries or APIs]
+- [Integration challenges with existing SolarWindPy components]
+
+**Scientific Risks**:
+- [Physics validation requirements and validation complexity]
+- [Numerical stability concerns and edge case handling]
+- [Data integrity and scientific correctness verification needs]
+
+**Operational Risks**:
+- [Maintenance burden and long-term support requirements]
+- [Documentation gaps and knowledge transfer challenges]
+- [Performance impact on existing workflows]
+
+**Risk Mitigation Strategies**:
+- [Specific approaches to manage and minimize identified risks]
+- [Validation protocols and testing strategies]
+- [Rollback plans and contingency procedures]
+
+### Value Proposition
+**Scientific Value**:
+- [Research enablement and new scientific capabilities unlocked]
+- [Reproducibility improvements and methodology advancements]
+- [Accuracy, precision, or efficiency gains for physics calculations]
+
+**Developer Value**:
+- [Code quality improvements and maintainability benefits]
+- [Reusability patterns and framework enhancements]
+- [Development velocity improvements for future work]
+
+**User Value**:
+- [Performance improvements and new features for end users]
+- [Documentation and usability enhancements]
+- [Workflow efficiency and productivity gains]
+
+**ROI Timeline**:
+- [Immediate benefits (0-1 months)]
+- [Medium-term value (1-6 months)]
+- [Long-term strategic value (6+ months)]
+
+### Cost Proposition
+**Development Time**:
+- [Estimated implementation hours with confidence intervals]
+- [Phase-by-phase time breakdown with uncertainty ranges]
+- [Complexity factors that may extend timeline]
+
+**Review & Testing Time**:
+- [Quality assurance and peer review effort]
+- [Physics validation and scientific testing requirements]
+- [Integration testing and regression validation]
+
+**Maintenance Cost**:
+- [Ongoing support and update requirements]
+- [Documentation maintenance and user support]
+- [Long-term compatibility and migration costs]
+
+**Opportunity Cost**:
+- [Other high-value work deferred by this plan]
+- [Resource allocation trade-offs and priority decisions]
+- [Strategic alternatives not pursued]
+
+### Token Proposition
+**Planning Tokens**:
+- [Estimated tokens for plan development and refinement]
+- [Cross-plan coordination and dependency analysis tokens]
+- [Research and design exploration token costs]
+
+**Implementation Tokens**:
+- [Estimated tokens for code development and testing]
+- [Documentation and example development tokens]
+- [Debugging and refinement iteration costs]
+
+**Future Token Savings**:
+- [Token reduction for similar future work through reusable patterns]
+- [Reduced planning overhead from documented approaches]
+- [Automated validation reducing manual checking tokens]
+
+**Net Token ROI**:
+- [Break-even point for token investment]
+- [Long-term token efficiency improvements]
+- [Multiplicative benefits for subsequent related work]
+
+### Usage Proposition
+**Target Users**:
+- [Primary user groups who will benefit from this change]
+- [Secondary beneficiaries and indirect value recipients]
+- [Specific researcher or developer personas addressed]
+
+**Usage Frequency**:
+- [Daily, weekly, monthly usage patterns expected]
+- [Peak usage scenarios and seasonal variations]
+- [Growth trajectory and adoption timeline]
+
+**Coverage Scope**:
+- [Percentage of SolarWindPy users/workflows affected]
+- [Geographic or institutional coverage considerations]
+- [Integration with existing research methodologies]
+
+**Adoption Requirements**:
+- [Training and documentation needs for users]
+- [Migration procedures and transition support]
+- [Change management and communication strategy]
+
 ## 🔧 Technical Requirements
 [Frameworks, dependencies, versions, and constraints]