claude-mpm 5.4.85__py3-none-any.whl → 5.6.1__py3-none-any.whl

claude_mpm/services/delegation_detector.py

@@ -0,0 +1,175 @@
+"""Delegation Pattern Detector for PM outputs.
+
+WHY this is needed:
+- Detect when PM asks user to do something manually instead of delegating
+- Convert manual instructions into actionable autotodos
+- Enforce delegation principle in PM workflow
+- Help PM recognize delegation opportunities
+
+DESIGN DECISION: Pattern-based detection
+- Simple regex patterns to catch common delegation anti-patterns
+- Extract action items from PM's output
+- Format as autotodos for PM to see and delegate properly
+- Non-invasive - just surfaces patterns for review
+
+Examples of patterns to detect:
+- "Make sure .env.local is in your .gitignore"
+- "You'll need to run npm install"
+- "Please run the tests manually"
+- "Remember to update the README"
+- "Don't forget to commit your changes"
+"""
+
+import re
+from typing import Any, Dict, List, Tuple
+
+from ..core.logger import get_logger
+
+# Delegation anti-patterns with capture groups for action extraction
+# Each pattern is (regex_pattern, todo_template)
+# {match} in template will be replaced with captured text
+USER_DELEGATION_PATTERNS: List[Tuple[str, str]] = [
+    # "Make sure (to) X" → "Verify: X"
+    (r"(?i)make sure (?:to |that |you )?(.+)", "Verify: {match}"),
+    # "You'll/will need to X" → "Task: X"
+    (r"(?i)you(?:'ll| will)? need to (.+)", "Task: {match}"),
+    # "Please run/execute/do X" → "Execute: X"
+    (r"(?i)please (?:run|execute|do) (.+)", "Execute: {match}"),
+    # "Remember to X" → "Task: X"
+    (r"(?i)remember to (.+)", "Task: {match}"),
+    # "Don't forget to X" → "Task: X"
+    (r"(?i)don'?t forget to (.+)", "Task: {match}"),
+    # "You should/can/could X" → "Suggested: X"
+    (r"(?i)you (?:should|can|could) (.+)", "Suggested: {match}"),
+    # "Be sure to X" → "Task: X"
+    (r"(?i)be sure to (.+)", "Task: {match}"),
+    # "Don't forget X" (without 'to') → "Task: X"
+    (r"(?i)don'?t forget (.+)", "Task: {match}"),
+    # "You may want to X" → "Suggested: X"
+    (r"(?i)you may want to (.+)", "Suggested: {match}"),
+    # "It's important to X" → "Task: X"
+    (r"(?i)it'?s important to (.+)", "Task: {match}"),
+]
+
+
+class DelegationDetector:
+    """Detects delegation anti-patterns in PM outputs.
+
+    WHY this design:
+    - Pattern-based detection for common manual instruction phrases
+    - Extract actionable tasks from PM's text
+    - Format as autotodos for PM visibility
+    - Simple and extensible (add new patterns easily)
+    """
+
+    def __init__(self):
+        self.logger = get_logger("delegation_detector")
+
+    def detect_user_delegation(self, text: str) -> List[Dict[str, Any]]:
+        """Detect delegation anti-patterns in text.
+
+        Scans text for patterns where PM is asking user to do something
+        manually instead of delegating to an agent.
+
+        Args:
+            text: PM output text to scan
+
+        Returns:
+            List of detected patterns with:
+                - pattern_type: Type of pattern matched
+                - original_text: Original sentence matched
+                - suggested_todo: Formatted todo text
+                - action: Extracted action text
+        """
+        detections = []
+
+        # Split into sentences for better pattern matching
+        # Split on period followed by space/newline, or just newline
+        # This avoids splitting on periods in filenames like .env.local
+        sentences = re.split(r"(?:\.\s+|\n+)", text)
+
+        for sentence in sentences:
+            sentence = sentence.strip()
+            if not sentence:
+                continue
+
+            # Try each pattern
+            for pattern, todo_template in USER_DELEGATION_PATTERNS:
+                match = re.search(pattern, sentence, re.IGNORECASE)
+                if match:
+                    # Extract the captured action
+                    action = match.group(1).strip()
+
+                    # Skip if action is too short (likely false positive)
+                    if len(action) < 5:
+                        continue
+
+                    # Format todo using template
+                    suggested_todo = todo_template.format(match=action)
+
+                    # Determine pattern type from template prefix
+                    pattern_type = todo_template.split(":")[0]
+
+                    detection = {
+                        "pattern_type": pattern_type,
+                        "original_text": sentence.strip(),
+                        "suggested_todo": suggested_todo,
+                        "action": action,
+                    }
+
+                    detections.append(detection)
+                    self.logger.debug(
+                        f"Detected delegation pattern: {pattern_type} - {action}"
+                    )
+
+                    # Only match first pattern per sentence
+                    break
+
+        return detections
+
+    def format_as_autotodo(self, detection: Dict[str, Any]) -> Dict[str, str]:
+        """Format a detection as an autotodo.
+
+        Args:
+            detection: Detection dict from detect_user_delegation
+
+        Returns:
+            Dictionary with todo fields (content, activeForm, status)
+        """
+        pattern_type = detection["pattern_type"]
+        suggested_todo = detection["suggested_todo"]
+        action = detection["action"]
+
+        # Create todo content
+        content = f"[Delegation] {suggested_todo}"
+
+        # Active form for in-progress display
+        active_form = f"Delegating: {action[:30]}..."
+
+        return {
+            "content": content,
+            "activeForm": active_form,
+            "status": "pending",
+            "metadata": {
+                "pattern_type": pattern_type,
+                "original_text": detection["original_text"],
+                "action": action,
+                "source": "delegation_detector",
+            },
+        }
+
+
+# Global instance
+_delegation_detector: DelegationDetector | None = None
+
+
+def get_delegation_detector() -> DelegationDetector:
+    """Get the global delegation detector instance.
+
+    Returns:
+        DelegationDetector instance
+    """
+    global _delegation_detector
+    if _delegation_detector is None:
+        _delegation_detector = DelegationDetector()
+    return _delegation_detector

claude_mpm/services/diagnostics/checks/agent_sources_check.py

@@ -69,6 +69,13 @@ class AgentSourcesCheck(BaseDiagnosticCheck):
                     fix_command="claude-mpm agent-source add https://github.com/bobmatnyc/claude-mpm-agents",
                     fix_description="Add default system repository",
                     sub_results=sub_results if self.verbose else [],
+                    explanation=(
+                        "Agent sources define where Claude MPM discovers specialized agents. "
+                        "Without configured sources, no agents can be deployed or delegated to. "
+                        "This is a critical component for multi-agent workflows."
+                    ),
+                    severity="critical",
+                    doc_link="https://github.com/bobmatnyc/claude-mpm/blob/main/docs/guides/agent-sources.md",
                 )
 
             # Check 2: Configuration is valid YAML
@@ -141,16 +148,30 @@ class AgentSourcesCheck(BaseDiagnosticCheck):
                 r for r in sub_results if r.status == ValidationSeverity.WARNING
             ]
 
+            # Determine status and enhanced troubleshooting info (issue #125)
             if error_results:
                 status = ValidationSeverity.ERROR
                 message = f"Agent sources have {len(error_results)} critical issue(s)"
                 fix_command = None
                 fix_description = None
+                severity = "critical"
+                explanation = (
+                    "Agent sources are the foundation of Claude MPM's delegation system. "
+                    "Critical errors prevent agent discovery and deployment, blocking "
+                    "multi-agent workflows entirely."
+                )
+                doc_link = "https://github.com/bobmatnyc/claude-mpm/blob/main/docs/guides/agent-sources.md"
             elif warning_results:
                 status = ValidationSeverity.WARNING
                 message = f"Agent sources have {len(warning_results)} minor issue(s)"
                 fix_command = "claude-mpm agent-source update"
                 fix_description = "Update all sources to refresh cache"
+                severity = "medium"
+                explanation = (
+                    "Some agent sources have issues but the system can still function. "
+                    "You may have limited agent availability or outdated cache."
+                )
+                doc_link = "https://github.com/bobmatnyc/claude-mpm/blob/main/docs/guides/agent-sources.md"
             else:
                 status = OperationResult.SUCCESS
                 enabled_count = details["enabled_sources"]
@@ -158,6 +179,12 @@ class AgentSourcesCheck(BaseDiagnosticCheck):
                 message = f"All checks passed ({enabled_count} source(s), {agents_count} agent(s))"
                 fix_command = None
                 fix_description = None
+                severity = "info"
+                explanation = (
+                    "Agent sources are properly configured and agents are discoverable. "
+                    "You can delegate tasks to specialized agents."
+                )
+                doc_link = ""
 
             return DiagnosticResult(
                 category=self.category,
@@ -167,6 +194,9 @@ class AgentSourcesCheck(BaseDiagnosticCheck):
                 fix_command=fix_command,
                 fix_description=fix_description,
                 sub_results=sub_results if self.verbose else [],
+                explanation=explanation,
+                severity=severity,
+                doc_link=doc_link,
             )
 
         except Exception as e:

claude_mpm/services/diagnostics/checks/configuration_check.py

@@ -63,12 +63,36 @@ class ConfigurationCheck(BaseDiagnosticCheck):
                 status = OperationResult.SUCCESS
                 message = "Configuration is valid"
 
+            # Add enhanced troubleshooting info (issue #125)
+            severity = "medium"
+            explanation = ""
+            doc_link = ""
+
+            if status == ValidationSeverity.ERROR:
+                severity = "high"
+                explanation = (
+                    "Configuration files control how Claude MPM behaves. Critical errors "
+                    "in configuration may prevent features from working correctly or cause "
+                    "unexpected behavior."
+                )
+                doc_link = "https://github.com/bobmatnyc/claude-mpm/blob/main/docs/configuration.md"
+            elif status == ValidationSeverity.WARNING:
+                severity = "low"
+                explanation = (
+                    "Configuration has minor issues that may affect optional features. "
+                    "Core functionality should still work."
+                )
+                doc_link = "https://github.com/bobmatnyc/claude-mpm/blob/main/docs/configuration.md"
+
             return DiagnosticResult(
                 category=self.category,
                 status=status,
                 message=message,
                 details=details,
                 sub_results=sub_results if self.verbose else [],
+                explanation=explanation,
+                severity=severity,
+                doc_link=doc_link,
             )
 
         except Exception as e:

claude_mpm/services/diagnostics/checks/installation_check.py

@@ -65,12 +65,34 @@ class InstallationCheck(BaseDiagnosticCheck):
                 status = OperationResult.SUCCESS
                 message = "Installation is healthy"
 
+            # Determine severity and explanation based on status (issue #125)
+            severity = "medium"
+            explanation = ""
+            doc_link = ""
+
+            if status == ValidationSeverity.ERROR:
+                severity = "high"
+                explanation = (
+                    "Claude MPM installation verification failed. Critical components are missing "
+                    "or misconfigured, which will prevent the system from functioning properly."
+                )
+                doc_link = "https://github.com/bobmatnyc/claude-mpm/blob/main/docs/installation.md"
+            elif status == ValidationSeverity.WARNING:
+                severity = "medium"
+                explanation = (
+                    "Installation is functional but has minor issues. These may affect "
+                    "performance or features but won't prevent basic operation."
+                )
+
             return DiagnosticResult(
                 category=self.category,
                 status=status,
                 message=message,
                 details=details,
                 sub_results=sub_results if self.verbose else [],
+                explanation=explanation,
+                severity=severity,
+                doc_link=doc_link,
             )
 
         except Exception as e:

claude_mpm/services/diagnostics/checks/mcp_services_check.py

@@ -216,12 +216,35 @@ class MCPServicesCheck(BaseDiagnosticCheck):
                 status = ValidationSeverity.WARNING
                 message = f"All {total_services} MCP services installed but connections not tested"
 
+            # Enhanced troubleshooting info (issue #125)
+            severity = "medium"
+            explanation = ""
+            doc_link = ""
+
+            if status == ValidationSeverity.ERROR:
+                severity = "high"
+                explanation = (
+                    "MCP services provide enhanced capabilities like vector search, browser automation, "
+                    "and ticket management. Critical errors prevent these services from functioning."
+                )
+                doc_link = "https://github.com/bobmatnyc/claude-mpm/blob/main/docs/mcp-services.md"
+            elif status == ValidationSeverity.WARNING:
+                severity = "low"
+                explanation = (
+                    "MCP services are optional but provide powerful features. "
+                    "Some services may not be installed or configured properly."
+                )
+                doc_link = "https://github.com/bobmatnyc/claude-mpm/blob/main/docs/mcp-services.md"
+
             return DiagnosticResult(
                 category=self.category,
                 status=status,
                 message=message,
                 details=details,
                 sub_results=sub_results if self.verbose else [],
+                explanation=explanation,
+                severity=severity,
+                doc_link=doc_link,
             )
 
         except Exception as e:

claude_mpm/services/diagnostics/doctor_reporter.py

@@ -28,6 +28,15 @@ class DoctorReporter:
         OperationResult.SKIPPED: "⏭️ ",
     }
 
+    # Severity level emojis (issue #125)
+    SEVERITY_SYMBOLS = {
+        "critical": "🔴",
+        "high": "🟠",
+        "medium": "🟡",
+        "low": "🟢",
+        "info": "🔵",
+    }
+
     # ANSI color codes
     COLORS = {
         "reset": "\033[0m",
@@ -93,8 +102,15 @@ class DoctorReporter:
         symbol = self.STATUS_SYMBOLS.get(result.status, "?")
         color = self._get_status_color(result.status)
 
+        # Add severity indicator if present (issue #125)
+        severity_prefix = ""
+        if result.severity and result.severity != "medium":
+            severity_symbol = self.SEVERITY_SYMBOLS.get(result.severity, "")
+            if severity_symbol:
+                severity_prefix = f"{severity_symbol} {result.severity.upper()}: "
+
         # Main result line
-        line = f"{indent_str}{symbol} {result.category}: "
+        line = f"{indent_str}{severity_prefix}{symbol} {result.category}: "
 
         if result.status == OperationResult.SUCCESS:
             line += self._color("OK", color)
@@ -111,6 +127,15 @@ class DoctorReporter:
         message_indent = "   " + indent_str
         print(f"{message_indent}{result.message}")
 
+        # Explanation (issue #125)
+        if result.explanation:
+            # Format multi-line explanations with proper indentation
+            explanation_lines = result.explanation.split("\n")
+            for explanation_line in explanation_lines:
+                print(
+                    f"{message_indent}{self._color(explanation_line.strip(), 'gray')}"
+                )
+
         # Details (in verbose mode)
         if self.verbose and result.details:
             for key, value in result.details.items():
@@ -126,6 +151,11 @@ class DoctorReporter:
             if result.fix_description:
                 print(f"{fix_indent}  {self._color(result.fix_description, 'gray')}")
 
+        # Documentation link (issue #125)
+        if result.doc_link:
+            doc_indent = "   " + indent_str
+            print(f"{doc_indent}{self._color('📖 Docs:', 'blue')} {result.doc_link}")
+
         # Sub-results (in verbose mode)
         if self.verbose and result.sub_results:
             for sub_result in result.sub_results:

claude_mpm/services/diagnostics/models.py

@@ -51,9 +51,14 @@ class DiagnosticResult:
     fix_description: Optional[str] = None
     sub_results: List["DiagnosticResult"] = field(default_factory=list)
 
+    # Enhanced troubleshooting fields (issue #125)
+    explanation: str = ""  # What this check means and why it matters
+    severity: str = "medium"  # critical, high, medium, low, info
+    doc_link: str = ""  # Link to relevant documentation
+
     def to_dict(self) -> Dict[str, Any]:
         """Convert to dictionary for JSON serialization."""
-        return {
+        result = {
             "category": self.category,
             "status": self.status.value,
             "message": self.message,
@@ -62,6 +67,14 @@ class DiagnosticResult:
             "fix_description": self.fix_description,
             "sub_results": [r.to_dict() for r in self.sub_results],
         }
+        # Include enhanced fields if present
+        if self.explanation:
+            result["explanation"] = self.explanation
+        if self.severity != "medium":
+            result["severity"] = self.severity
+        if self.doc_link:
+            result["doc_link"] = self.doc_link
+        return result
 
     @property
     def has_issues(self) -> bool: