empathy-framework 4.6.6__py3-none-any.whl → 4.7.0__py3-none-any.whl

empathy_software_plugin/wizards/ai_documentation_wizard.py

@@ -1,503 +0,0 @@
-"""AI-First Documentation Wizard - Level 4 Anticipatory Empathy
-
-Alerts developers when documentation patterns will limit AI effectiveness.
-
-In our experience, documentation written for humans often confuses AI.
-This wizard learned to predict when documentation gaps will cause AI
-to give poor recommendations, before developers waste time debugging why.
-
-Copyright 2025 Smart AI Memory, LLC
-Licensed under Fair Source 0.9
-"""
-
-import os
-import sys
-from typing import Any
-
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", "src"))
-
-from empathy_os.plugins import BaseWizard
-
-
-class AIDocumentationWizard(BaseWizard):
-    """Level 4 Anticipatory: Ensures documentation serves AI and humans.
-
-    Key Insight from Experience:
-    When we started using AI coding assistants heavily, we discovered our
-    documentation was great for humans but terrible for AI. Comments that
-    made perfect sense to us confused AI. Missing context that humans inferred
-    caused AI to make wrong assumptions.
-
-    This wizard helps you write documentation that makes AI a better partner.
-    """
-
-    def __init__(self):
-        super().__init__(
-            name="AI-First Documentation Wizard",
-            domain="software",
-            empathy_level=4,
-            category="ai_development",
-        )
-
-    def get_required_context(self) -> list[str]:
-        """Required context for analysis"""
-        return [
-            "documentation_files",  # READMEs, docs, comments
-            "code_files",  # Source files with docstrings
-            "project_path",  # Project root
-        ]
-
-    async def analyze(self, context: dict[str, Any]) -> dict[str, Any]:
-        """Analyze documentation quality for AI collaboration.
-
-        In our experience: Documentation gaps only become obvious when
-        AI gives wrong answers. This wizard alerts you proactively.
-        """
-        self.validate_context(context)
-
-        doc_files = context["documentation_files"]
-        code_files = context.get("code_files", [])
-
-        # Current issues
-        issues = await self._analyze_ai_documentation_quality(doc_files, code_files)
-
-        # Level 4: Predict when gaps will cause AI failures
-        predictions = await self._predict_ai_confusion_points(doc_files, code_files, context)
-
-        recommendations = self._generate_recommendations(issues, predictions)
-        patterns = self._extract_patterns(issues, predictions)
-
-        return {
-            "issues": issues,
-            "predictions": predictions,
-            "recommendations": recommendations,
-            "patterns": patterns,
-            "confidence": 0.85,
-            "metadata": {
-                "wizard": self.name,
-                "empathy_level": self.empathy_level,
-                "docs_analyzed": len(doc_files),
-                "code_files_analyzed": len(code_files),
-            },
-        }
-
-    async def _analyze_ai_documentation_quality(
-        self,
-        doc_files: list[str],
-        code_files: list[str],
-    ) -> list[dict[str, Any]]:
-        """Analyze current documentation from AI perspective.
-
-        Checks what AI needs to give good recommendations.
-        """
-        issues: list[dict[str, Any]] = []
-
-        # Check for missing context that AI needs
-        for doc_file in doc_files:
-            try:
-                with open(doc_file) as f:
-                    content = f.read()
-            except OSError:
-                continue
-
-            # AI needs explicit architecture context
-            if "README" in doc_file.upper():
-                if not self._has_architecture_overview(content):
-                    issues.append(
-                        {
-                            "severity": "warning",
-                            "type": "missing_architecture_context",
-                            "file": doc_file,
-                            "message": (
-                                "README lacks architecture overview. In our experience, "
-                                "AI makes better suggestions when it understands system structure."
-                            ),
-                            "suggestion": (
-                                "Add ## Architecture section explaining: "
-                                "components, data flow, key abstractions"
-                            ),
-                        },
-                    )
-
-                # AI needs explicit technology choices explained
-                if not self._has_technology_rationale(content):
-                    issues.append(
-                        {
-                            "severity": "info",
-                            "type": "missing_tech_rationale",
-                            "file": doc_file,
-                            "message": (
-                                "Technology choices not explained. AI assumes common patterns "
-                                "when context is missing, which may not match your approach."
-                            ),
-                            "suggestion": (
-                                "Add ## Technology Choices section explaining WHY you chose "
-                                "specific libraries/frameworks (not just WHAT you use)"
-                            ),
-                        },
-                    )
-
-            # Check for ambiguous language (confuses AI)
-            ambiguous_phrases = self._find_ambiguous_phrases(content)
-            if ambiguous_phrases:
-                issues.append(
-                    {
-                        "severity": "info",
-                        "type": "ambiguous_language",
-                        "file": doc_file,
-                        "message": (
-                            f"Found {len(ambiguous_phrases)} ambiguous phrases. "
-                            "AI interprets these literally, unlike humans who infer meaning."
-                        ),
-                        "examples": ambiguous_phrases[:3],
-                        "suggestion": "Be explicit. Replace 'usually', 'normally', 'try to' with precise rules.",
-                    },
-                )
-
-        # Check code documentation
-        for code_file in code_files[:10]:  # Sample first 10
-            try:
-                with open(code_file) as f:
-                    content = f.read()
-            except OSError:
-                continue
-
-            # Check for missing type hints (AI relies on these)
-            if code_file.endswith(".py"):
-                if not self._has_type_hints(content):
-                    issues.append(
-                        {
-                            "severity": "warning",
-                            "type": "missing_type_hints",
-                            "file": code_file,
-                            "message": (
-                                "Missing type hints. In our experience, AI gives 60-80% better "
-                                "suggestions when types are explicit."
-                            ),
-                            "suggestion": "Add type hints to function signatures and class attributes",
-                        },
-                    )
-
-            # Check for missing docstrings with examples
-            if not self._has_docstring_examples(content):
-                issues.append(
-                    {
-                        "severity": "info",
-                        "type": "missing_docstring_examples",
-                        "file": code_file,
-                        "message": (
-                            "Docstrings lack examples. AI learns your patterns from examples. "
-                            "Without them, AI guesses based on generic knowledge."
-                        ),
-                        "suggestion": ("Add Examples section to docstrings showing actual usage"),
-                    },
-                )
-
-        return issues
-
-    async def _predict_ai_confusion_points(
-        self,
-        doc_files: list[str],
-        code_files: list[str],
-        full_context: dict[str, Any],
-    ) -> list[dict[str, Any]]:
-        """Level 4: Predict where documentation gaps will confuse AI.
-
-        Based on our experience: AI confusion follows predictable patterns.
-        """
-        predictions = []
-
-        # Pattern 1: Implicit conventions
-        if not self._has_explicit_conventions(doc_files):
-            predictions.append(
-                {
-                    "type": "implicit_conventions_confusion",
-                    "alert": (
-                        "No explicit coding conventions documented. "
-                        "In our experience, AI assumes common conventions when not specified. "
-                        "Alert: If your project has unique patterns, AI will generate code "
-                        "that doesn't match your style, causing review friction."
-                    ),
-                    "probability": "high",
-                    "impact": "medium",
-                    "prevention_steps": [
-                        "Create CONVENTIONS.md documenting your patterns",
-                        "Include: naming conventions, file organization, error handling",
-                        "Add examples of 'good' vs 'avoid' code",
-                        "Reference conventions in prompts to AI tools",
-                    ],
-                    "reasoning": (
-                        "AI learns from billions of repos. Your specific conventions "
-                        "get lost in that noise unless you make them explicit."
-                    ),
-                    "personal_experience": (
-                        "We use specific patterns in Empathy Framework (e.g., wizard base classes). "
-                        "Before documenting these, AI would suggest generic patterns. "
-                        "After documenting, AI suggestions matched our architecture 90%+ of time."
-                    ),
-                },
-            )
-
-        # Pattern 2: Missing 'why' context
-        total_why_ratio = self._calculate_why_ratio(doc_files)
-        if total_why_ratio < 0.2:  # Less than 20% 'why' content
-            predictions.append(
-                {
-                    "type": "missing_why_context",
-                    "alert": (
-                        f"Documentation is {(1 - total_why_ratio) * 100:.0f}% 'what/how', "
-                        f"only {total_why_ratio * 100:.0f}% 'why'. "
-                        "In our experience, AI needs 'why' context to make good design decisions. "
-                        "Alert: Without 'why', AI suggests technically correct but strategically wrong solutions."
-                    ),
-                    "probability": "high",
-                    "impact": "high",
-                    "prevention_steps": [
-                        "Add 'Design Decisions' section to README",
-                        "Document WHY you chose specific approaches",
-                        "Explain WHY you avoided common alternatives",
-                        "Include context: constraints, requirements, tradeoffs",
-                    ],
-                    "reasoning": (
-                        "AI can generate any solution. Without 'why' context, "
-                        "it picks based on generic best practices, not your needs."
-                    ),
-                    "personal_experience": (
-                        "When we documented WHY we chose 5 empathy levels (not 3 or 7), "
-                        "AI started suggesting features that fit the framework. "
-                        "Before, it suggested generic improvements that didn't align."
-                    ),
-                },
-            )
-
-        # Pattern 3: No decision log
-        if not self._has_decision_log(doc_files):
-            predictions.append(
-                {
-                    "type": "missing_decision_history",
-                    "alert": (
-                        "No decision log found (ADR, decision.md, etc.). "
-                        "In our experience, AI repeats past mistakes when it doesn't "
-                        "know what was already tried and rejected. "
-                        "Alert: You'll waste time having AI suggest approaches you already ruled out."
-                    ),
-                    "probability": "medium-high",
-                    "impact": "medium",
-                    "prevention_steps": [
-                        "Create docs/decisions/ directory",
-                        "Document: 'We tried X, it failed because Y, we chose Z instead'",
-                        "Use Architecture Decision Records (ADR) format",
-                        "Update when you reject AI suggestions (so it learns)",
-                    ],
-                    "reasoning": (
-                        "AI doesn't know your history. It will confidently suggest "
-                        "the approach you spent 2 weeks discovering doesn't work."
-                    ),
-                },
-            )
-
-        # Pattern 4: Documentation-code drift
-        if len(code_files) > 20:  # Substantial codebase
-            drift_indicators = self._detect_documentation_drift(doc_files, code_files)
-            if drift_indicators > 3:
-                predictions.append(
-                    {
-                        "type": "documentation_drift",
-                        "alert": (
-                            f"Detected {drift_indicators} indicators of documentation-code drift. "
-                            "In our experience, stale docs cause AI to generate code for "
-                            "architecture that no longer exists. "
-                            "Alert: Review and update docs before drift compounds."
-                        ),
-                        "probability": "high",
-                        "impact": "high",
-                        "prevention_steps": [
-                            "Add 'Last Updated' dates to all docs",
-                            "Create documentation review checklist for PRs",
-                            "Implement doc tests (code examples in docs that run)",
-                            "Set up automated stale doc detection",
-                        ],
-                        "reasoning": (
-                            "Code evolves faster than docs. Without active maintenance, "
-                            "docs describe the system you HAD, not the one you HAVE."
-                        ),
-                    },
-                )
-
-        # Pattern 5: No AI-specific guidance
-        if not self._has_ai_guidance(doc_files):
-            predictions.append(
-                {
-                    "type": "missing_ai_collaboration_guide",
-                    "alert": (
-                        "No guidance for AI collaboration found. "
-                        "In our experience, explicitly telling AI how you want to work with it "
-                        "improves quality dramatically. Alert: Add AI collaboration guide "
-                        "before your team develops inconsistent AI usage patterns."
-                    ),
-                    "probability": "medium",
-                    "impact": "medium",
-                    "prevention_steps": [
-                        "Create AI_COLLABORATION.md",
-                        "Document: How to prompt for this codebase",
-                        "Include: Context to provide, patterns to follow, pitfalls to avoid",
-                        "Add examples of good AI interactions for this project",
-                    ],
-                    "reasoning": (
-                        "Different projects need different AI collaboration styles. "
-                        "Explicit guidance creates consistency across team."
-                    ),
-                    "personal_experience": (
-                        "We created AI collaboration guides for Empathy Framework development. "
-                        "Result: AI suggestions became 3x more relevant because we taught it "
-                        "our patterns explicitly."
-                    ),
-                },
-            )
-
-        return predictions
-
-    def _generate_recommendations(self, issues: list[dict], predictions: list[dict]) -> list[str]:
-        """Generate actionable recommendations"""
-        recommendations = []
-
-        # Quick wins
-        type_hint_issues = [i for i in issues if i["type"] == "missing_type_hints"]
-        if type_hint_issues:
-            recommendations.append(
-                f"[QUICK WIN] Add type hints to {len(type_hint_issues)} files. "
-                "In our experience, this immediately improves AI suggestion quality 60-80%.",
-            )
-
-        # High-impact predictions
-        for pred in predictions:
-            if pred.get("impact") in ["high", "medium"]:
-                recommendations.append(f"\n[ALERT] {pred['alert']}")
-                if "personal_experience" in pred:
-                    recommendations.append(f"Experience: {pred['personal_experience']}")
-                recommendations.append("\nRecommended actions:")
-                for i, step in enumerate(pred["prevention_steps"][:3], 1):
-                    recommendations.append(f"  {i}. {step}")
-
-        return recommendations
-
-    def _extract_patterns(
-        self,
-        issues: list[dict],
-        predictions: list[dict],
-    ) -> list[dict[str, Any]]:
-        """Extract cross-domain patterns"""
-        return [
-            {
-                "pattern_type": "context_for_ai_collaboration",
-                "description": (
-                    "Systems that explicitly document context for AI collaboration "
-                    "(conventions, decisions, 'why' rationale) get dramatically better AI assistance"
-                ),
-                "domain_agnostic": True,
-                "applicable_to": [
-                    "Software development",
-                    "Clinical protocols (healthcare)",
-                    "Legal documentation",
-                    "Any domain using AI assistance",
-                ],
-                "key_elements": [
-                    "Explicit conventions (not assumed)",
-                    "'Why' context (not just 'what')",
-                    "Decision history (what was tried/rejected)",
-                    "Examples of desired patterns",
-                    "AI collaboration guidance",
-                ],
-            },
-        ]
-
-    # Helper methods
-
-    def _has_architecture_overview(self, content: str) -> bool:
-        """Check for architecture explanation"""
-        keywords = ["architecture", "components", "structure", "design"]
-        return any(kw in content.lower() for kw in keywords)
-
-    def _has_technology_rationale(self, content: str) -> bool:
-        """Check for technology choice explanations"""
-        return "why we chose" in content.lower() or "decision" in content.lower()
-
-    def _find_ambiguous_phrases(self, content: str) -> list[str]:
-        """Find phrases that confuse AI"""
-        ambiguous = [
-            "usually",
-            "normally",
-            "typically",
-            "should probably",
-            "might want to",
-            "try to",
-        ]
-        found = []
-        for phrase in ambiguous:
-            if phrase in content.lower():
-                found.append(phrase)
-        return found
-
-    def _has_type_hints(self, content: str) -> bool:
-        """Check if Python code has type hints"""
-        return "->" in content or ": int" in content or ": str" in content
-
-    def _has_docstring_examples(self, content: str) -> bool:
-        """Check if docstrings include examples"""
-        return "Example" in content or ">>>" in content or "<example>" in content
-
-    def _has_explicit_conventions(self, doc_files: list[str]) -> bool:
-        """Check for documented conventions"""
-        for filepath in doc_files:
-            if "convention" in filepath.lower() or "style" in filepath.lower():
-                return True
-            try:
-                with open(filepath) as f:
-                    if "convention" in f.read().lower():
-                        return True
-            except OSError:
-                pass
-        return False
-
-    def _calculate_why_ratio(self, doc_files: list[str]) -> float:
-        """Calculate ratio of 'why' content to total content"""
-        total_chars = 0
-        why_chars = 0
-
-        for filepath in doc_files:
-            try:
-                with open(filepath) as f:
-                    content = f.read()
-                    total_chars += len(content)
-
-                    # Rough heuristic: count 'why' sections
-                    why_sections = content.lower().count("why")
-                    why_sections += content.lower().count("rationale")
-                    why_sections += content.lower().count("decision")
-                    why_chars += why_sections * 100  # Estimate
-            except OSError:
-                pass
-
-        if total_chars == 0:
-            return 0
-        return min(1.0, why_chars / total_chars)
-
-    def _has_decision_log(self, doc_files: list[str]) -> bool:
-        """Check for decision/ADR documentation"""
-        for filepath in doc_files:
-            if "decision" in filepath.lower() or "adr" in filepath.lower():
-                return True
-        return False
-
-    def _detect_documentation_drift(self, doc_files: list[str], code_files: list[str]) -> int:
-        """Detect indicators of doc-code drift"""
-        # Simplified: just return indicator count
-        # Real implementation would compare doc references to actual code
-        return len(doc_files) // 3  # Rough heuristic
-
-    def _has_ai_guidance(self, doc_files: list[str]) -> bool:
-        """Check for AI collaboration guidance"""
-        for filepath in doc_files:
-            if "ai" in filepath.lower() and "collab" in filepath.lower():
-                return True
-        return False