fix: Add keyword-based session type detection for investigation/troubleshooting (#1604) (#1606)

fix: Add keyword-based session type detection for investigation/troubleshooting (#1604)

This PR fixes #1604 where power-steering incorrectly blocked investigation and
troubleshooting sessions with development-specific checks.

**Changes:**
- Add INVESTIGATION_KEYWORDS constant (16 keywords)
- Add _has_investigation_keywords() helper method
- Update detect_session_type() to check keywords FIRST before tool heuristics
- Add 19 comprehensive tests for keyword detection
- Document fix in DISCOVERIES.md

**The core insight:** User intent (expressed through keywords like "investigate",
"troubleshoot", "debug") is more reliable than tool usage patterns for
classifying session types.

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

Co-Authored-By: Claude <noreply@anthropic.com>

Author: rysweet

.claude/context/DISCOVERIES.md

@@ -4,6 +4,44 @@ This file documents non-obvious problems, solutions, and patterns discovered
 during development. It serves as a living knowledge base that grows with the
 project.
 
+## Power-Steering Session Type Detection Fix (2025-11-25)
+
+### Problem
+
+Power-steering was incorrectly blocking investigation/troubleshooting sessions with development-specific checks (PR, CI/CD, tests). Sessions like "Investigate SSH connection issues" were being classified as DEVELOPMENT or MAINTENANCE based on tool usage patterns (Bash commands, doc updates), even though they should be INVESTIGATION.
+
+### Root Cause
+
+The `detect_session_type()` method relied solely on tool-based heuristics:
+
+- Bash commands → could indicate DEVELOPMENT (tests) or MAINTENANCE (git)
+- Doc file edits → MAINTENANCE
+- Read/Grep operations → INVESTIGATION (but only if no writes)
+
+Troubleshooting sessions often involve:
+
+- Bash commands to diagnose/fix issues (SSH, docker, etc.)
+- Doc updates (DISCOVERIES.md) to record findings
+- These patterns were misclassified
+
+### Solution (PR #1606)
+
+Added **keyword-based session type detection** with priority over tool heuristics:
+
+1. Check first 5 user messages for investigation keywords
+2. Keywords include: investigate, troubleshoot, diagnose, debug, analyze, research, explore, understand, figure out, why does, how does, what causes, root cause, explain
+3. If found → immediately classify as INVESTIGATION
+4. Fall back to tool-based heuristics only if no keywords
+
+### Key Insight
+
+**User intent (expressed through keywords) is more reliable than tool usage patterns** for classifying session types. A user saying "troubleshoot the SSH issue" clearly wants an investigation, regardless of what tools get used.
+
+### Files Changed
+
+- `.claude/tools/amplihack/hooks/power_steering_checker.py`: Added `INVESTIGATION_KEYWORDS`, `_has_investigation_keywords()`, updated `detect_session_type()`
+- `.claude/tools/amplihack/hooks/tests/test_session_classification.py`: Added 18 tests for keyword detection
+
 ## Transcripts System Investigation - Architecture Validated, Microsoft Amplifier Comparison Complete (2025-11-22)
 
 ### Investigation Summary

.claude/tools/amplihack/hooks/power_steering_checker.py

@@ -196,6 +196,35 @@ class PowerSteeringChecker:
         "python -m unittest",
     ]
 
+    # Keywords that indicate investigation/troubleshooting sessions
+    # When found in early user messages, session is classified as INVESTIGATION
+    # regardless of tool usage patterns (fixes #1604)
+    #
+    # Note: Using substring matching, so shorter forms match longer variants:
+    # - "troubleshoot" matches "troubleshooting"
+    # - "diagnos" matches "diagnose", "diagnosis", "diagnosing"
+    # - "debug" matches "debugging"
+    INVESTIGATION_KEYWORDS = [
+        "investigate",
+        "troubleshoot",
+        "diagnos",  # matches diagnose, diagnosis, diagnosing
+        "analyze",
+        "analyse",
+        "research",
+        "explore",
+        "understand",
+        "figure out",
+        "why does",
+        "why is",
+        "how does",
+        "how is",
+        "what causes",
+        "what's causing",
+        "root cause",
+        "debug",
+        "explain",
+    ]
+
     # Phase 1 fallback: Hardcoded considerations (top 5 critical)
     # Used when YAML file is missing or invalid
     PHASE1_CONSIDERATIONS = [
@@ -981,14 +1010,57 @@ def _has_investigation_indicators(
         # Multiple Read/Grep without modifications
         return read_grep_operations >= 2 and write_edit_operations == 0
 
+    def _has_investigation_keywords(self, transcript: List[Dict]) -> bool:
+        """Check early user messages for investigation/troubleshooting keywords.
+
+        This check takes PRIORITY over tool-based heuristics. If investigation
+        keywords are found, the session is classified as INVESTIGATION regardless
+        of what tools were used. This fixes #1604 where troubleshooting sessions
+        were incorrectly blocked by development-specific checks.
+
+        Args:
+            transcript: List of message dictionaries
+
+        Returns:
+            True if investigation keywords found in early user messages
+        """
+        # Check first 5 user messages for investigation keywords
+        user_messages = [m for m in transcript if m.get("type") == "user"][:5]
+
+        if not user_messages:
+            return False
+
+        for msg in user_messages:
+            content = str(msg.get("message", {}).get("content", "")).lower()
+
+            # Check for investigation keywords
+            for keyword in self.INVESTIGATION_KEYWORDS:
+                if keyword in content:
+                    self._log(
+                        f"Investigation keyword '{keyword}' found in user message",
+                        "DEBUG",
+                    )
+                    return True
+
+        return False
+
     def detect_session_type(self, transcript: List[Dict]) -> str:
         """Detect session type for selective consideration application.
 
         Session Types:
         - DEVELOPMENT: Code changes, tests, PR operations
         - INFORMATIONAL: Q&A, help queries, capability questions
         - MAINTENANCE: Documentation and configuration updates only
-        - INVESTIGATION: Read-only exploration and analysis
+        - INVESTIGATION: Exploration, analysis, troubleshooting, and debugging
+
+        Detection Priority (fixes #1604):
+        1. Environment override (AMPLIHACK_SESSION_TYPE)
+        2. Investigation keywords in user messages (highest priority heuristic)
+        3. Tool usage patterns (code changes, tests, etc.)
+
+        The keyword detection takes priority over tool-based heuristics because
+        troubleshooting sessions often involve Bash commands and doc updates,
+        which can be misclassified as DEVELOPMENT or MAINTENANCE.
 
         Args:
             transcript: List of message dictionaries
@@ -1006,6 +1078,12 @@ def detect_session_type(self, transcript: List[Dict]) -> str:
         if not transcript:
             return "INFORMATIONAL"
 
+        # PRIORITY CHECK: Investigation keywords in user messages
+        # This takes precedence over tool-based heuristics (fixes #1604)
+        if self._has_investigation_keywords(transcript):
+            self._log("Session classified as INVESTIGATION via keyword detection", "INFO")
+            return "INVESTIGATION"
+
         # Collect indicators from transcript
         code_files_modified = False
         doc_files_only = True