@jaguilar87/gaia-ops 2.2.3 → 2.3.0

package/CHANGELOG.md

@@ -5,6 +5,54 @@ All notable changes to the CLAUDE.md orchestrator instructions are documented in
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.0] - 2025-11-11
+
+### Added - Phase 0 Clarification Module
+- **NEW:** `tools/clarification/` module for intelligent ambiguity detection before routing
+  - `clarification/engine.py`: Core clarification engine (refactored from clarify_engine.py)
+  - `clarification/patterns.py`: Ambiguity detection patterns (ServiceAmbiguityPattern, NamespaceAmbiguityPattern, etc.)
+  - `clarification/workflow.py`: High-level helper functions for orchestrators (`execute_workflow()`)
+  - `clarification/__init__.py`: Clean public API
+- **Protocol G** in `agents/gaia.md`: Clarification system analysis and troubleshooting guide
+- **Rule 5.0.1** in `templates/CLAUDE.template.md`: Phase 0 implementation guide with code examples
+- **Phase 0 integration** in `/speckit.specify` command
+- **Regression tests** in `tests/integration/test_phase_0_regression.py`
+- **Clarification metrics** to Key System Metrics (target: 20-30% clarification rate)
+
+### Changed - Module Restructuring (BREAKING)
+- **BREAKING:** `clarify_engine.py` and `clarify_patterns.py` moved to `clarification/` module
+  - **Old imports:** `from clarify_engine import request_clarification`
+  - **New imports:** `from clarification import execute_workflow, request_clarification`
+- Updated `application_services` structure in project-context.json:
+  - Added `tech_stack` field (replaces `technology`)
+  - Added `namespace` field for service location
+  - **Removed** `status` field (dynamic state must be verified in real-time, not stored in SSOT)
+- Service metadata now shows only static information: `tech_stack | namespace | port`
+
+### Fixed
+- Import paths in `tests/tools/test_clarify_engine.py` updated to new module structure
+- Service metadata test updated to reflect removal of dynamic status field
+- All 20 unit tests passing with new module structure
+
+### Documentation
+- Added comprehensive Phase 0 implementation guide
+- Added troubleshooting guide for clarification system
+- Updated speckit.specify.md with Phase 0 workflow integration
+- Added Protocol G diagnostic steps in gaia.md
+
+### Migration Guide for v2.3.0
+```python
+# Before (v2.2.x)
+from clarify_engine import request_clarification, process_clarification
+
+# After (v2.3.0)
+from clarification import execute_workflow
+
+# Simple usage
+result = execute_workflow(user_prompt)
+enriched_prompt = result["enriched_prompt"]
+```
+
 ## [2.2.3] - 2025-11-11
 
 ### Fixed - Deterministic Project Context Location

package/agents/gaia.md

@@ -113,6 +113,8 @@ When `npx @jaguilar87/gaia-ops init` (or `gaia-init` after a global install) run
 ### Key System Metrics (What to Track)
 
 - **Routing Accuracy:** Target 92.7% (from tests)
+- **Clarification Rate:** Target 20-30% (Phase 0 effectiveness)
+- **Clarification Effectiveness:** Routing accuracy improvement post-enrichment
 - **Context Efficiency:** 79-85% token savings (via context_provider.py)
 - **Test Coverage:** 55+ tests, 100% pass rate
 - **Production Uptime:** Track via logs/
@@ -472,6 +474,88 @@ You:
 
 **Output:** Feature RFC (Request for Comments)
 
+### Protocol G: Clarification System Analysis
+
+**Trigger:** "¿Por qué no se activó clarificación?" or "Ambiguity detection issues" or "Analyze Phase 0"
+
+**Steps:**
+1. Review clarification logs:
+   ```bash
+   cat .claude/logs/clarifications.jsonl | jq .
+   ```
+
+2. Check configuration:
+   ```bash
+   cat .claude/config/clarification_rules.json
+   jq '.global_settings' .claude/config/clarification_rules.json
+   ```
+
+3. Test detection manually:
+   ```python
+   import sys
+   sys.path.insert(0, '.claude/tools')
+   from clarification import execute_workflow, request_clarification
+
+   result = request_clarification("Check the API")
+   print(f"Needs clarification: {result['needs_clarification']}")
+   print(f"Ambiguity score: {result.get('ambiguity_score', 0)}")
+   print(f"Patterns detected: {[a['pattern'] for a in result.get('ambiguity_points', [])]}")
+   ```
+
+4. Review pattern definitions:
+   ```bash
+   cat .claude/tools/clarification/patterns.py
+   ```
+
+5. Analyze recent clarifications:
+   ```bash
+   cat .claude/logs/clarifications.jsonl | \
+     jq -r '[.timestamp, .ambiguity_score, .original_prompt] | @csv' | \
+     tail -20
+   ```
+
+6. Benchmark effectiveness:
+   - **Clarification rate:** Target 20-30%
+   - **User satisfaction:** No complaints about "too many questions"
+   - **Routing accuracy improvement:** Measure before/after enrichment
+
+7. Check module structure:
+   ```bash
+   ls -la .claude/tools/clarification/
+   # Should show: __init__.py, engine.py, patterns.py, workflow.py
+   ```
+
+**Output:** Clarification effectiveness report + tuning recommendations
+
+**Common Issues:**
+
+| Issue | Symptom | Fix |
+|-------|---------|-----|
+| Threshold too high | Ambiguity not detected | Lower from 30 to 20 in `clarification_rules.json` |
+| Threshold too low | Too many questions | Raise from 30 to 40 |
+| Missing patterns | New ambiguous terms not caught | Add to `patterns.py` (ServiceAmbiguityPattern.keywords) |
+| Spanish keywords missing | Spanish prompts not detected | Add to keywords list in patterns |
+| Import errors | Module not found | Check symlinks to gaia-ops package |
+| No services found | Tests failing | Verify `project-context.json` has `application_services` section |
+
+**Metrics to Track:**
+
+```python
+# Calculate clarification rate
+import json
+
+with open('.claude/logs/clarifications.jsonl') as f:
+    logs = [json.loads(line) for line in f]
+
+total_requests = len(logs)
+clarified = sum(1 for log in logs if log.get('ambiguity_score', 0) > 30)
+rate = (clarified / total_requests * 100) if total_requests > 0 else 0
+
+print(f"Clarification rate: {rate:.1f}%")
+print(f"Target: 20-30%")
+print(f"Status: {'✅ Good' if 20 <= rate <= 30 else '⚠️ Needs tuning'}")
+```
+
 ## Research Guidelines (WebSearch Usage)
 
 When researching, follow this pattern:

package/commands/speckit.specify.md

@@ -31,32 +31,23 @@ Given those arguments, do this:
 
    ```python
    import sys
-   sys.path.insert(0, '/home/jaguilar/aaxis/rnd/repositories/.claude/tools')
-   from clarify_engine import request_clarification, process_clarification
+   sys.path.insert(0, '.claude/tools')
+   from clarification import execute_workflow
 
-   # Detect ambiguity in feature description
-   clarification_data = request_clarification(
+   # Detect and resolve ambiguity in feature description
+   result = execute_workflow(
        user_prompt=feature_description,
-       command_context={"command": "speckit.specify"}
+       command_context={"command": "speckit.specify"},
+       ask_user_question_func=AskUserQuestion  # Claude Code tool
    )
 
-   if clarification_data["needs_clarification"]:
-       # Present summary
-       print(clarification_data["summary"])
+   # Use enriched description for remaining steps
+   feature_description = result["enriched_prompt"]
 
-       # Ask questions (AskUserQuestion tool)
-       response = AskUserQuestion(**clarification_data["question_config"])
-
-       # Enrich feature description
-       result = process_clarification(
-           clarification_data["engine_instance"],
-           feature_description,
-           response["answers"],
-           clarification_data["clarification_context"]
-       )
-
-       # Use enriched description for remaining steps
-       feature_description = result["enriched_prompt"]
+   # Log clarification if it occurred
+   if result["clarification_occurred"]:
+       from clarification import get_clarification_summary
+       print(get_clarification_summary(result["clarification_data"]))
    ```
 
    **What gets clarified**:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaguilar87/gaia-ops",
-  "version": "2.2.3",
+  "version": "2.3.0",
   "description": "Multi-agent orchestration system for Claude Code - DevOps automation toolkit",
   "main": "index.js",
   "type": "module",

package/templates/CLAUDE.template.md

@@ -27,7 +27,7 @@
 
 | Phase | Action | Tool | Mandatory |
 |-------|--------|------|-----------|
-| 0 | Clarification (if ambiguous) | `clarify_engine.py` | Conditional |
+| 0 | Clarification (if ambiguous) | `clarification` module | Conditional |
 | 1 | Route to agent | `agent_router.py` | Yes |
 | 2 | Provision context | `context_provider.py` | Yes |
 | 3 | Invoke (Planning) | `Task` tool | Yes |
@@ -37,6 +37,55 @@
 
 **See:** `.claude/config/orchestration-workflow.md` for complete details.
 
+### Rule 5.0.1 [P0]: Phase 0 Implementation
+
+**When to invoke Phase 0:**
+- User prompt contains generic terms: "the service", "the API", "the cluster"
+- User mentions "production" but project-context says "non-prod"
+- User references resource without specifying which (Redis, DB, namespace)
+- Ambiguity score > 30 (threshold configurable in `.claude/config/clarification_rules.json`)
+
+**When to skip Phase 0:**
+- User prompt is specific: "tcm-api in tcm-non-prod"
+- Read-only queries: "show me logs"
+- Simple commands: "/help", "/status"
+
+**Code Integration:**
+
+```python
+import sys
+sys.path.insert(0, '.claude/tools')
+from clarification import execute_workflow
+
+# At orchestrator entry point
+result = execute_workflow(
+    user_prompt=user_prompt,
+    command_context={"command": "general_prompt"}
+)
+
+enriched_prompt = result["enriched_prompt"]
+
+# Then proceed to Phase 1 with enriched_prompt
+# agent = route_to_agent(enriched_prompt)
+```
+
+**Manual Mode (custom UX):**
+
+```python
+from clarification import execute_workflow
+
+result = execute_workflow(user_prompt)  # No ask_user_question_func
+
+if result.get("needs_manual_questioning"):
+    # Show summary and questions to user
+    print(result["summary"])
+
+    # Get user responses with custom UI
+    # Then manually process clarification
+```
+
+**See:** `.claude/config/orchestration-workflow.md` lines 25-150 for complete Phase 0 protocol.
+
 ### Rule 5.1 [P0]: Approval Gate Enforcement
 - Phase 4 CANNOT be skipped for T3 operations
 - Phase 5 requires `validation["approved"] == True`

package/tests/integration/test_phase_0_regression.py

@@ -0,0 +1,175 @@
+"""
+Phase 0 Regression Tests
+
+Regression tests for specific cases that should trigger clarification.
+These tests validate real-world scenarios where ambiguity detection is critical.
+"""
+
+import pytest
+import sys
+import os
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..', 'tools'))
+
+from clarification import request_clarification, execute_workflow
+
+
+def test_regression_valida_servicio_tcm():
+    """
+    Regression test for: "valida el servicio de tcm"
+
+    This SHOULD trigger clarification because:
+    1. "el servicio" is ambiguous (ServiceAmbiguityPattern)
+    2. "tcm" is not a specific service name (could be tcm-api, tcm-web, tcm-bot, tcm-jobs)
+    3. "validar" is generic (no specific action)
+
+    Expected behavior:
+    - Detect service ambiguity
+    - Ambiguity score >= 30 (above threshold)
+    - Offer options: tcm-api, tcm-web, tcm-bot, tcm-jobs
+    """
+
+    user_request = "valida el servicio de tcm"
+
+    # Phase 0: Should detect ambiguity
+    clarification = request_clarification(user_request)
+
+    # Assertions
+    assert clarification["needs_clarification"] == True, \
+        "Should need clarification for ambiguous service reference"
+
+    assert clarification["ambiguity_score"] >= 30, \
+        f"Ambiguity score {clarification['ambiguity_score']} should be >= 30"
+
+    # Should detect service ambiguity pattern
+    service_ambiguity = next(
+        (a for a in clarification.get("ambiguity_points", [])
+         if "service" in a["pattern"]),
+        None
+    )
+
+    assert service_ambiguity is not None, \
+        "Should detect service ambiguity pattern"
+
+    # Should offer service options containing "tcm"
+    available_options = service_ambiguity.get("available_options", [])
+    tcm_services = [opt for opt in available_options if "tcm" in opt.lower()]
+
+    assert len(tcm_services) > 0, \
+        f"Should offer TCM services, got: {available_options}"
+
+
+def test_regression_check_the_api():
+    """
+    Regression test for: "Check the API"
+
+    Generic reference to "the API" when multiple APIs exist should trigger clarification.
+    """
+
+    clarification = request_clarification("Check the API")
+
+    assert clarification["needs_clarification"] == True
+    assert clarification["ambiguity_score"] > 30
+
+    # Should detect service ambiguity
+    patterns = [a["pattern"] for a in clarification.get("ambiguity_points", [])]
+    assert "service_ambiguity" in patterns
+
+
+def test_regression_deploy_to_cluster():
+    """
+    Regression test for: "Deploy to cluster"
+
+    Missing namespace specification should trigger clarification.
+    """
+
+    clarification = request_clarification("Deploy to cluster")
+
+    assert clarification["needs_clarification"] == True
+
+    # Should detect namespace ambiguity
+    patterns = [a["pattern"] for a in clarification.get("ambiguity_points", [])]
+    assert "namespace_ambiguity" in patterns
+
+
+def test_regression_deploy_to_production():
+    """
+    Regression test for: "Deploy to production"
+
+    When project-context says "non-prod" but user mentions "production",
+    should trigger environment warning.
+    """
+
+    clarification = request_clarification("Deploy to production")
+
+    assert clarification["needs_clarification"] == True
+
+    # Should detect environment mismatch
+    patterns = [a["pattern"] for a in clarification.get("ambiguity_points", [])]
+    assert "environment_ambiguity" in patterns
+
+    # Should have high weight (90)
+    env_ambiguity = next(
+        (a for a in clarification.get("ambiguity_points", [])
+         if "environment" in a["pattern"]),
+        None
+    )
+    assert env_ambiguity["weight"] >= 80, \
+        "Environment mismatch should have high weight"
+
+
+def test_no_clarification_for_specific_prompt():
+    """
+    Test that specific prompts do NOT trigger clarification.
+
+    "Check tcm-api service in tcm-non-prod namespace" is fully qualified
+    and should not need clarification.
+    """
+
+    clarification = request_clarification(
+        "Check tcm-api service in tcm-non-prod namespace"
+    )
+
+    assert clarification["needs_clarification"] == False, \
+        "Specific prompt should not need clarification"
+
+    assert clarification.get("ambiguity_score", 0) <= 30, \
+        "Specific prompt should have low ambiguity score"
+
+
+def test_spanish_keywords_detection():
+    """
+    Test that Spanish keywords are properly detected.
+
+    "Chequea el servicio" should trigger same clarification as "Check the service"
+    """
+
+    clarification = request_clarification("Chequea el servicio")
+
+    assert clarification["needs_clarification"] == True
+
+    # Should detect service ambiguity
+    patterns = [a["pattern"] for a in clarification.get("ambiguity_points", [])]
+    assert "service_ambiguity" in patterns
+
+
+def test_execute_workflow_without_ask_function():
+    """
+    Test execute_workflow in manual mode (no ask_user_question_func).
+
+    Should return questions for manual handling.
+    """
+
+    result = execute_workflow("Check the API")
+
+    assert result.get("needs_manual_questioning") == True
+    assert "questions" in result
+    assert len(result["questions"]) > 0
+    assert "summary" in result
+
+    # Original prompt not enriched yet
+    assert result["enriched_prompt"] == "Check the API"
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

package/tests/tools/test_clarify_engine.py

@@ -1,5 +1,5 @@
 """
-Unit tests for clarify_engine.py
+Unit tests for clarification module
 """
 
 import pytest
@@ -11,7 +11,7 @@ import os
 tools_path = os.path.join(os.path.dirname(__file__), '..', '..', 'tools')
 sys.path.insert(0, tools_path)
 
-from clarify_engine import ClarificationEngine, request_clarification, process_clarification
+from clarification import ClarificationEngine, request_clarification, process_clarification
 
 
 @pytest.fixture
@@ -338,8 +338,7 @@ def test_get_option_metadata_service(engine_with_mock_context):
             "tcm-api": {
                 "tech_stack": "NestJS",
                 "namespace": "tcm-non-prod",
-                "port": 3001,
-                "status": "running"
+                "port": 3001
             }
         }
     }
@@ -349,7 +348,7 @@ def test_get_option_metadata_service(engine_with_mock_context):
     assert "NestJS" in metadata
     assert "tcm-non-prod" in metadata
     assert "3001" in metadata
-    assert "✅" in metadata  # Running status emoji
+    # Status is NOT in project-context (verified in real-time only)
 
 
 def test_get_option_metadata_namespace(engine_with_mock_context):

package/tools/clarification/__init__.py

@@ -0,0 +1,52 @@
+"""
+Clarification Module
+
+Intelligent ambiguity detection and prompt enrichment for Phase 0 of the
+orchestration workflow.
+
+This module detects ambiguous user prompts (e.g., "check the API" when multiple
+APIs exist) and generates targeted clarification questions with rich options
+from project-context.json.
+
+Public API:
+    - execute_workflow(): High-level function for orchestrators
+    - request_clarification(): Detect ambiguity and generate questions
+    - process_clarification(): Enrich prompt with user responses
+    - ClarificationEngine: Core engine class
+    - detect_all_ambiguities(): Pattern-based detection
+
+Example usage:
+    from clarification import execute_workflow
+
+    result = execute_workflow("check the API")
+    enriched_prompt = result["enriched_prompt"]
+"""
+
+from .engine import (
+    ClarificationEngine,
+    request_clarification,
+    process_clarification
+)
+
+from .patterns import detect_all_ambiguities
+
+from .workflow import (
+    execute_workflow,
+    should_skip_clarification,
+    get_clarification_summary
+)
+
+__all__ = [
+    # Main workflow function (recommended for orchestrators)
+    'execute_workflow',
+    'should_skip_clarification',
+    'get_clarification_summary',
+
+    # Lower-level functions (for advanced usage)
+    'ClarificationEngine',
+    'request_clarification',
+    'process_clarification',
+    'detect_all_ambiguities',
+]
+
+__version__ = '1.0.0'

package/tools/{clarify_engine.py → clarification/engine.py}

@@ -52,7 +52,7 @@ class ClarificationEngine:
             }
         """
         # Import patterns here to avoid circular dependency
-        from clarify_patterns import detect_all_ambiguities
+        from .patterns import detect_all_ambiguities
 
         # Step 1: Detect all ambiguities using patterns
         ambiguities = detect_all_ambiguities(user_prompt, self.project_context)
@@ -330,10 +330,10 @@ class ClarificationEngine:
             tech_stack = svc.get("tech_stack", "N/A")
             namespace = svc.get("namespace", "N/A")
             port = svc.get("port", "N/A")
-            status = svc.get("status", "unknown")
-            status_emoji = "✅" if status == "running" else "⏸️"
 
-            return f"{tech_stack} | Namespace: {namespace} | Puerto: {port} | Estado: {status_emoji} {status}"
+            # Status is NOT stored in project-context (must be verified in real-time)
+            # Only show static metadata
+            return f"{tech_stack} | Namespace: {namespace} | Puerto: {port}"
 
         # Namespace metadata
         elif pattern == "namespace_ambiguity" and "namespace_metadata" in ambiguity:

package/tools/clarification/workflow.py

@@ -0,0 +1,205 @@
+"""
+Clarification Workflow Functions
+
+High-level helper functions for orchestrators to integrate Phase 0 clarification
+with minimal code changes.
+"""
+
+import sys
+from typing import Dict, Any, Optional
+
+from .engine import request_clarification, process_clarification
+
+
+def execute_workflow(
+    user_prompt: str,
+    command_context: Optional[Dict[str, Any]] = None,
+    ask_user_question_func: Optional[callable] = None
+) -> Dict[str, Any]:
+    """
+    Execute complete Phase 0 clarification workflow.
+
+    This is the main entry point for orchestrators. It handles:
+    1. Ambiguity detection
+    2. Question generation
+    3. User interaction (if ask function provided)
+    4. Prompt enrichment
+
+    Args:
+        user_prompt: Original user request
+        command_context: Optional context (e.g., {"command": "speckit.specify"})
+        ask_user_question_func: Function to ask questions (e.g., AskUserQuestion tool)
+                                If None, returns questions for manual handling
+
+    Returns:
+        {
+            "enriched_prompt": str,              # Enriched or original prompt
+            "clarification_occurred": bool,       # True if clarification happened
+            "clarification_data": Dict or None,   # Full clarification data (for logging)
+            "questions": List[Dict],              # Questions asked (if any)
+
+            # Only if ask_user_question_func is None:
+            "needs_manual_questioning": bool,     # True if manual question handling needed
+            "summary": str                        # Clarification summary to show user
+        }
+
+    Example (automatic mode - with AskUserQuestion):
+        from clarification import execute_workflow
+
+        result = execute_workflow(
+            user_prompt="check the API",
+            ask_user_question_func=AskUserQuestion  # Claude Code tool
+        )
+        enriched_prompt = result["enriched_prompt"]
+
+    Example (manual mode - for custom UX):
+        result = execute_workflow("check the API")
+
+        if result.get("needs_manual_questioning"):
+            print(result["summary"])
+            for q in result["questions"]:
+                # Show question to user with custom UI
+                # Get user response
+                # Then call process_clarification manually
+    """
+
+    # Step 1: Detect ambiguity
+    clarification = request_clarification(
+        user_prompt=user_prompt,
+        command_context=command_context or {"command": "general_prompt"}
+    )
+
+    # Step 2: Decision point - no clarification needed
+    if not clarification["needs_clarification"]:
+        return {
+            "enriched_prompt": user_prompt,
+            "clarification_occurred": False,
+            "clarification_data": None,
+            "questions": []
+        }
+
+    # Step 3: If no ask function provided, return questions for manual handling
+    if ask_user_question_func is None:
+        return {
+            "enriched_prompt": user_prompt,  # Not enriched yet
+            "clarification_occurred": False,
+            "clarification_data": clarification,
+            "questions": clarification["question_config"]["questions"],
+            "summary": clarification["summary"],
+            "needs_manual_questioning": True
+        }
+
+    # Step 4: Ask user questions (using provided function)
+    try:
+        user_responses = ask_user_question_func(**clarification["question_config"])
+    except Exception as e:
+        # If questioning fails, return original prompt
+        print(f"Warning: Failed to ask clarification questions: {e}", file=sys.stderr)
+        return {
+            "enriched_prompt": user_prompt,
+            "clarification_occurred": False,
+            "clarification_data": None,
+            "questions": [],
+            "error": str(e)
+        }
+
+    # Step 5: Enrich prompt with responses
+    result = process_clarification(
+        engine_instance=clarification["engine_instance"],
+        original_prompt=user_prompt,
+        user_responses=user_responses.get("answers", {}),
+        clarification_context=clarification["clarification_context"]
+    )
+
+    return {
+        "enriched_prompt": result["enriched_prompt"],
+        "clarification_occurred": True,
+        "clarification_data": {
+            "original_prompt": user_prompt,
+            "ambiguity_score": clarification.get("ambiguity_score", 0),
+            "patterns_detected": [a["pattern"] for a in clarification.get("ambiguity_points", [])],
+            "user_responses": user_responses.get("answers", {})
+        },
+        "questions": clarification["question_config"]["questions"]
+    }
+
+
+def should_skip_clarification(
+    user_prompt: str,
+    command_context: Optional[Dict[str, Any]] = None
+) -> bool:
+    """
+    Quick check if Phase 0 should be skipped for this prompt.
+
+    Skip clarification for:
+    - System commands (starts with "/")
+    - Read-only queries with low ambiguity ("show", "get", "list")
+    - Already-specific prompts (includes service name, namespace, etc.)
+
+    Args:
+        user_prompt: User's request
+        command_context: Optional command context
+
+    Returns:
+        True if Phase 0 should be skipped, False otherwise
+
+    Example:
+        if should_skip_clarification("/help"):
+            # Skip Phase 0
+        else:
+            # Execute Phase 0
+    """
+
+    # Skip system commands
+    if user_prompt.strip().startswith("/"):
+        return True
+
+    # For read-only queries, use higher ambiguity threshold
+    read_only_keywords = ["show", "get", "list", "ver", "mostrar", "listar", "view"]
+    if any(keyword in user_prompt.lower() for keyword in read_only_keywords):
+        clarification = request_clarification(user_prompt, command_context)
+        # Higher threshold (50 instead of 30) for read-only operations
+        return clarification.get("ambiguity_score", 0) < 50
+
+    return False
+
+
+def get_clarification_summary(clarification_data: Dict[str, Any]) -> str:
+    """
+    Generate human-readable summary of clarification that occurred.
+
+    Useful for logging or displaying to user.
+
+    Args:
+        clarification_data: Clarification data from execute_workflow()
+
+    Returns:
+        String summary (multi-line)
+
+    Example:
+        result = execute_workflow("check the API")
+        if result["clarification_occurred"]:
+            print(get_clarification_summary(result["clarification_data"]))
+    """
+
+    if not clarification_data:
+        return "No clarification needed"
+
+    original = clarification_data.get("original_prompt", "N/A")
+    score = clarification_data.get("ambiguity_score", 0)
+    patterns = clarification_data.get("patterns_detected", [])
+    responses = clarification_data.get("user_responses", {})
+
+    lines = []
+    lines.append("=" * 60)
+    lines.append("PHASE 0 CLARIFICATION SUMMARY")
+    lines.append("=" * 60)
+    lines.append(f"Original prompt: {original}")
+    lines.append(f"Ambiguity score: {score}/100")
+    lines.append(f"Patterns detected: {', '.join(patterns)}")
+    lines.append(f"\nUser responses:")
+    for question_id, answer in responses.items():
+        lines.append(f"  {question_id}: {answer}")
+    lines.append("=" * 60)
+
+    return "\n".join(lines)