refactor: Professional code quality improvements (Option 2)

Code Quality Enhancements:

1. Logging Improvements (48 changes)
   - Replaced all print() statements in cli.py with structured logging
   - Used logger.info() for success/status messages
   - Used logger.error() for error messages
   - Improved log consistency and management

2. Exception Handling (25 fixes)
   - Fixed all bare except clauses in wizard files
   - Changed `except:` to `except OSError:` for file I/O operations
   - Improved debuggability and error visibility
   - Files: agent_orchestration, ai_collaboration, ai_documentation,
     multi_model, prompt_engineering, rag_pattern wizards

3. Documentation (5 abstract methods)
   - Added comprehensive Google-style docstrings to all abstract methods
   - Enhanced EmpathyLevel.respond() with implementation guidance
   - Documented BaseWizard.analyze() and get_required_context()
   - Documented BasePlugin.get_metadata() and register_wizards()
   - Added 149 lines of developer guidance

4. Code Modernization (1 fix)
   - Removed outdated Python 3.9 compatibility code from registry.py
   - Aligned with project's Python 3.10+ requirement
   - Cleaned up unnecessary version checking

Impact:
- Better logging: 48 print() → logger calls for structured output
- Better errors: 25 bare excepts → specific OSError catching
- Better docs: 5 abstract methods with comprehensive guidance
- Cleaner code: Removed deprecated version checks

Files Modified: 10
Lines Changed: ~200
Code Quality: Significantly improved

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

Co-Authored-By: Claude <[email protected]>

Author: 2 people

empathy_software_plugin/wizards/agent_orchestration_wizard.py

@@ -361,7 +361,7 @@ def _has_state_management(self, orchestration: list[str]) -> bool:
                         for kw in ["StateGraph", "AgentState", "shared_state", "TypedDict"]
                     ):
                         return True
-            except:
+            except OSError:
                 pass
         return False
 
@@ -374,7 +374,7 @@ def _has_agent_error_handling(self, orchestration: list[str]) -> bool:
                     # Look for error handling patterns
                     if "try:" in content and "agent" in content.lower():
                         return True
-            except:
+            except OSError:
                 pass
         return False
 
@@ -421,7 +421,7 @@ def _all_sequential(self, orchestration: list[str]) -> bool:
                         for kw in ["asyncio.gather", "ThreadPool", "parallel", "concurrent"]
                     ):
                         return False
-            except:
+            except OSError:
                 pass
         return True
 
@@ -442,6 +442,6 @@ def _has_observability(self, orchestration: list[str]) -> bool:
                         kw in content for kw in ["logger", "trace", "span", "metrics", "telemetry"]
                     ):
                         return True
-            except:
+            except OSError:
                 pass
         return False

empathy_software_plugin/wizards/ai_collaboration_wizard.py

@@ -445,7 +445,7 @@ def _detect_reactive_patterns(self, files: list[str]) -> int:
                     if "ai.generate" in content or "openai." in content or "anthropic." in content:
                         if "context" not in content.lower() and "history" not in content.lower():
                             reactive_count += 1
-            except:
+            except OSError:
                 pass
         return reactive_count
 
@@ -494,6 +494,6 @@ def _has_any_keyword(self, files: list[str], keywords: list[str]) -> bool:
                     content = f.read()
                     if any(kw in content for kw in keywords):
                         return True
-            except:
+            except OSError:
                 pass
         return False

empathy_software_plugin/wizards/ai_documentation_wizard.py

@@ -99,7 +99,7 @@ async def _analyze_ai_documentation_quality(
             try:
                 with open(doc_file) as f:
                     content = f.read()
-            except:
+            except OSError:
                 continue
 
             # AI needs explicit architecture context
@@ -161,7 +161,7 @@ async def _analyze_ai_documentation_quality(
             try:
                 with open(code_file) as f:
                     content = f.read()
-            except:
+            except OSError:
                 continue
 
             # Check for missing type hints (AI relies on these)
@@ -453,7 +453,7 @@ def _has_explicit_conventions(self, doc_files: list[str]) -> bool:
                 with open(filepath) as f:
                     if "convention" in f.read().lower():
                         return True
-            except:
+            except OSError:
                 pass
         return False
 
@@ -473,7 +473,7 @@ def _calculate_why_ratio(self, doc_files: list[str]) -> float:
                     why_sections += content.lower().count("rationale")
                     why_sections += content.lower().count("decision")
                     why_chars += why_sections * 100  # Estimate
-            except:
+            except OSError:
                 pass
 
         if total_chars == 0:

empathy_software_plugin/wizards/multi_model_wizard.py

@@ -388,7 +388,7 @@ def _has_model_abstraction(self, routing: list[str]) -> bool:
                         for kw in ["ModelRouter", "ModelRegistry", "AbstractModel", "UnifiedAPI"]
                     ):
                         return True
-            except:
+            except OSError:
                 pass
         return False
 
@@ -400,7 +400,7 @@ def _has_fallback_strategy(self, routing: list[str]) -> bool:
                     content = f.read()
                     if "fallback" in content.lower() or "retry" in content.lower():
                         return True
-            except:
+            except OSError:
                 pass
         return False
 
@@ -419,7 +419,7 @@ def _has_cost_tracking(self, routing: list[str]) -> bool:
                         "track" in content.lower() or "log" in content.lower()
                     ):
                         return True
-            except:
+            except OSError:
                 pass
         return False
 
@@ -434,7 +434,7 @@ def _has_performance_monitoring(self, routing: list[str]) -> bool:
                         for kw in ["latency", "metrics", "monitoring", "telemetry"]
                     ):
                         return True
-            except:
+            except OSError:
                 pass
         return False
 
@@ -446,7 +446,7 @@ def _has_cost_optimization(self, routing: list[str]) -> bool:
                     content = f.read()
                     if "cache" in content.lower() or "budget" in content.lower():
                         return True
-            except:
+            except OSError:
                 pass
         return False
 
@@ -458,7 +458,7 @@ def _has_output_validation(self, routing: list[str]) -> bool:
                     content = f.read()
                     if any(kw in content for kw in ["Pydantic", "validate", "schema", "BaseModel"]):
                         return True
-            except:
+            except OSError:
                 pass
         return False
 
@@ -471,7 +471,7 @@ def _has_version_tracking(self, routing: list[str]) -> bool:
                     # Look for specific version strings
                     if "gpt-4-" in content or "claude-3" in content or "version" in content.lower():
                         return True
-            except:
+            except OSError:
                 pass
         return False
 
@@ -492,6 +492,6 @@ def _has_smart_routing(self, routing: list[str]) -> bool:
                         ]
                     ):
                         return True
-            except:
+            except OSError:
                 pass
         return False

empathy_software_plugin/wizards/prompt_engineering_wizard.py

@@ -414,13 +414,13 @@ def _has_version_marker(self, filepath: str) -> bool:
             with open(filepath) as f:
                 content = f.read()
                 return bool(re.search(r"v\d+\.\d+\.\d+|version:", content, re.IGNORECASE))
-        except:
+        except OSError:
             return False
 
     def _estimate_token_count(self, filepath: str) -> int:
         """Rough estimate of token count (chars / 4)"""
         try:
             with open(filepath) as f:
                 return len(f.read()) // 4
-        except:
+        except OSError:
             return 0

empathy_software_plugin/wizards/rag_pattern_wizard.py

@@ -387,7 +387,7 @@ def _has_reranking(self, rag_impl: list[str]) -> bool:
                         kw in content.lower() for kw in ["rerank", "cross-encoder", "cohere.rerank"]
                     ):
                         return True
-            except:
+            except OSError:
                 pass
         return False
 
@@ -399,7 +399,7 @@ def _has_hybrid_search(self, rag_impl: list[str]) -> bool:
                     content = f.read()
                     if any(kw in content.lower() for kw in ["hybrid", "bm25", "keyword", "fusion"]):
                         return True
-            except:
+            except OSError:
                 pass
         return False
 
@@ -414,7 +414,7 @@ def _has_query_understanding(self, rag_impl: list[str]) -> bool:
                         for kw in ["query_rewrite", "query_expansion", "decompose", "intent"]
                     ):
                         return True
-            except:
+            except OSError:
                 pass
         return False
 
@@ -429,7 +429,7 @@ def _has_evaluation(self, rag_impl: list[str]) -> bool:
                         for kw in ["evaluate", "metrics", "ground_truth", "precision", "recall"]
                     ):
                         return True
-            except:
+            except OSError:
                 pass
         return False
 
@@ -444,6 +444,6 @@ def _has_context_optimization(self, rag_impl: list[str]) -> bool:
                         for kw in ["prune", "summarize", "deduplicate", "context_budget"]
                     ):
                         return True
-            except:
+            except OSError:
                 pass
         return False