feat: improve ha_report_issue with title, duplicate check, and markdown formatting (#484)

* feat: improve ha_report_issue with title, duplicate check, and markdown formatting

- Add automatic title generation based on error messages or connection status
- Add duplicate check URLs for searching similar issues before submission
- Update instructions to guide agents to present reports in markdown code blocks
- Add search keywords generation for duplicate detection
- Update tests to verify new features

Closes #467

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

* refactor: address Gemini code review feedback

- Use direct log iteration in _generate_search_keywords (fixes bug in string parsing)
- Use urllib.parse.quote_plus for proper URL encoding
- Define URL constants to avoid duplication across templates and instructions
- Refactor title truncation logic to avoid duplication
- Add test fixture for unwrapping decorated function
- Make test assertions more specific and verify search keywords in URLs

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

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: julienld

src/ha_mcp/tools/tools_bug_report.py

@@ -11,6 +11,7 @@
 import sys
 from pathlib import Path
 from typing import Annotated, Any
+from urllib.parse import quote_plus
 
 from pydantic import Field
 
@@ -21,6 +22,10 @@
 
 logger = logging.getLogger(__name__)
 
+# GitHub issue template URLs
+RUNTIME_BUG_URL = "https://github.com/homeassistant-ai/ha-mcp/issues/new?template=runtime_bug.md"
+AGENT_BEHAVIOR_URL = "https://github.com/homeassistant-ai/ha-mcp/issues/new?template=agent_behavior_feedback.md"
+
 
 def _detect_installation_method() -> str:
     """
@@ -226,6 +231,16 @@ async def ha_report_issue(
         # Anonymization instructions
         anonymization_guide = _generate_anonymization_guide()
 
+        # Generate suggested title
+        suggested_title = _generate_bug_title(diagnostic_info, recent_logs)
+
+        # Generate search keywords and URLs for duplicate check
+        search_keywords = _generate_search_keywords(diagnostic_info, recent_logs)
+        duplicate_check_urls = [
+            f"https://github.com/homeassistant-ai/ha-mcp/issues?q=is%3Aissue+{quote_plus(keyword)}"
+            for keyword in search_keywords[:3]  # Limit to top 3 keywords
+        ]
+
         return {
             "success": True,
             "diagnostic_info": diagnostic_info,
@@ -237,21 +252,35 @@ async def ha_report_issue(
             "runtime_bug_template": runtime_bug_template,
             "agent_behavior_template": agent_behavior_template,
             "anonymization_guide": anonymization_guide,
+            "suggested_title": suggested_title,
+            "duplicate_check_urls": duplicate_check_urls,
             "instructions": (
-                "ANALYZE THE CONVERSATION to determine which template to present:\n\n"
-                "🐛 Present RUNTIME_BUG_TEMPLATE if:\n"
-                "   - User reports an error, failure, or unexpected behavior in ha-mcp\n"
-                "   - A tool returned an error or incorrect result\n"
-                "   - Something is broken or not working\n"
-                "   Submit at: https://github.com/homeassistant-ai/ha-mcp/issues/new?template=runtime_bug.md\n\n"
-                "🤖 Present AGENT_BEHAVIOR_TEMPLATE if:\n"
-                "   - User mentions YOU (the agent) used the wrong tool\n"
-                "   - User suggests YOU should have done something differently\n"
-                "   - User reports YOUR inefficiency or mistakes\n"
-                "   Submit at: https://github.com/homeassistant-ai/ha-mcp/issues/new?template=agent_behavior_feedback.md\n\n"
-                "If UNCLEAR which type, ASK: 'Are you reporting a bug in ha-mcp, or providing feedback on how I used the tools?'\n\n"
-                "Present the chosen template to the user. Ask them to fill in the description sections. "
-                "Remind them to follow the anonymization_guide to protect their privacy."
+                "WORKFLOW FOR PRESENTING BUG REPORTS:\n\n"
+                "1. **Check for duplicates FIRST** (before presenting the template):\n"
+                "   - Use the duplicate_check_urls to search for similar issues\n"
+                "   - If gh CLI is available: use `gh issue list --search \"keyword\"`\n"
+                "   - Otherwise: inform user to check the duplicate_check_urls\n"
+                "   - If duplicates found, ask user if they want to comment on existing issue instead\n\n"
+                "2. **Determine which template to present**:\n"
+                "   - ANALYZE THE CONVERSATION to determine which template to present\n\n"
+                "   🐛 Present RUNTIME_BUG_TEMPLATE if:\n"
+                "      - User reports an error, failure, or unexpected behavior in ha-mcp\n"
+                "      - A tool returned an error or incorrect result\n"
+                "      - Something is broken or not working\n\n"
+                "   🤖 Present AGENT_BEHAVIOR_TEMPLATE if:\n"
+                "      - User mentions YOU (the agent) used the wrong tool\n"
+                "      - User suggests YOU should have done something differently\n"
+                "      - User reports YOUR inefficiency or mistakes\n\n"
+                "   If UNCLEAR which type, ASK: 'Are you reporting a bug in ha-mcp, or providing feedback on how I used the tools?'\n\n"
+                "3. **Present the report to the user**:\n"
+                "   a. Show the suggested_title (user can edit if needed)\n"
+                "   b. Present the chosen template IN A MARKDOWN CODE BLOCK (```markdown...```) for easy copy/paste\n"
+                "   c. PROMINENTLY display the submission URL at the top:\n"
+                f"      - Runtime bugs: {RUNTIME_BUG_URL}\n"
+                f"      - Agent behavior: {AGENT_BEHAVIOR_URL}\n"
+                "   d. Ask them to fill in the description sections\n"
+                "   e. Remind them to follow the anonymization_guide to protect their privacy\n\n"
+                "CRITICAL: Always present templates in markdown code blocks (```markdown...```) so users can copy/paste easily!"
             ),
         }
 
@@ -322,6 +351,84 @@ def _extract_error_messages(logs: list[dict[str, Any]]) -> list[str]:
     return error_messages
 
 
+def _generate_bug_title(
+    diagnostic_info: dict[str, Any],
+    recent_logs: list[dict[str, Any]],
+) -> str:
+    """
+    Generate a concise bug title (single line, ~60 chars max).
+
+    Strategy:
+    1. If there are error messages, use the most recent one as basis
+    2. Otherwise, use generic template based on connection status
+    3. Truncate to ~60 chars max
+    """
+    title = ""
+    # Try to get the most recent error directly from logs
+    for log in reversed(recent_logs):
+        error_msg = log.get("error_message")
+        if error_msg:
+            tool_name = log.get("tool_name", "unknown")
+            title = f"{tool_name}: {error_msg}"
+            break
+
+    if not title:
+        # No errors - check connection status
+        conn_status = diagnostic_info.get("connection_status", "Unknown")
+        if "Error" in conn_status or "Failed" in conn_status:
+            title = f"Connection issue: {conn_status}"
+        else:
+            title = "Issue with ha-mcp"
+
+    # Truncate to ~60 chars, trying to preserve words
+    if len(title) > 60:
+        title = title[:57] + "..."
+
+    return title
+
+
+def _generate_search_keywords(
+    diagnostic_info: dict[str, Any],
+    recent_logs: list[dict[str, Any]],
+) -> list[str]:
+    """
+    Generate search keywords for duplicate issue detection.
+
+    Returns a list of keywords to search for similar issues.
+    """
+    keywords = set()
+
+    # Find the most recent error from logs
+    last_error_log = next((log for log in reversed(recent_logs) if log.get("error_message")), None)
+
+    if last_error_log:
+        tool_name = last_error_log.get("tool_name")
+        if tool_name:
+            keywords.add(tool_name)
+
+        error_msg = last_error_log.get("error_message", "").lower()
+        # Common error patterns
+        if "connection" in error_msg:
+            keywords.add("connection")
+        if "timeout" in error_msg:
+            keywords.add("timeout")
+        if "authentication" in error_msg or "auth" in error_msg:
+            keywords.add("authentication")
+        if "not found" in error_msg:
+            keywords.add("not found")
+
+    # Add connection-based keywords
+    conn_status = diagnostic_info.get("connection_status", "Unknown")
+    if "Error" in conn_status or "Failed" in conn_status:
+        keywords.add("connection")
+
+    # Default to generic search if no specific keywords
+    if not keywords:
+        keywords.add("bug")
+
+    return list(keywords)
+
+
 def _generate_runtime_bug_template(
     diagnostic_info: dict[str, Any],
     log_summary: str,
@@ -365,7 +472,7 @@ def _generate_runtime_bug_template(
 > All environment info and logs below were collected automatically.
 
 **Submit this report at:**
-https://github.com/homeassistant-ai/ha-mcp/issues/new?template=runtime_bug.md
+{RUNTIME_BUG_URL}
 
 ---
 
@@ -456,7 +563,7 @@ def _generate_agent_behavior_template(
 > Tool call history was collected automatically to help analyze agent behavior.
 
 **Submit this feedback at:**
-https://github.com/homeassistant-ai/ha-mcp/issues/new?template=agent_behavior_feedback.md
+{AGENT_BEHAVIOR_URL}
 
 ---
 

tests/src/unit/test_tools_bug_report.py

@@ -42,6 +42,15 @@ def registered_tools(self, mock_mcp, mock_client):
         register_bug_report_tools(mock_mcp, mock_client)
         return mock_mcp
 
+    @pytest.fixture
+    def ha_report_issue_func(self, registered_tools):
+        """Return the unwrapped ha_report_issue function."""
+        ha_report_issue = registered_tools._tools["ha_report_issue"]
+        actual_func = ha_report_issue
+        while hasattr(actual_func, "__wrapped__"):
+            actual_func = actual_func.__wrapped__
+        return actual_func
+
     @pytest.mark.asyncio
     async def test_bug_report_success(self, registered_tools, mock_client):
         """Test successful bug report generation."""
@@ -77,6 +86,8 @@ async def test_bug_report_success(self, registered_tools, mock_client):
         assert "recent_logs" in result
         assert "log_count" in result
         assert "instructions" in result
+        assert "suggested_title" in result
+        assert "duplicate_check_urls" in result
 
         # Check diagnostic info
         diag = result["diagnostic_info"]
@@ -314,3 +325,118 @@ async def test_bug_report_instructions(self, registered_tools, mock_client):
         assert "AGENT_BEHAVIOR_TEMPLATE" in instructions
         assert "ANALYZE THE CONVERSATION" in instructions
         assert "privacy" in instructions.lower()
+
+    @pytest.mark.asyncio
+    async def test_bug_report_suggested_title(self, ha_report_issue_func, mock_client):
+        """Test that a suggested title is generated."""
+        mock_client.get_config.return_value = {"version": "2024.12.0"}
+        mock_client.get_states.return_value = []
+
+        with patch(
+            "ha_mcp.tools.tools_bug_report.get_recent_logs"
+        ) as mock_get_logs:
+            mock_get_logs.return_value = [
+                {
+                    "timestamp": "2024-12-01T10:00:00",
+                    "tool_name": "ha_call_service",
+                    "success": False,
+                    "execution_time_ms": 50,
+                    "error_message": "Service not found",
+                },
+            ]
+
+            result = await ha_report_issue_func()
+
+            # Check suggested title is present and has correct format
+            assert "suggested_title" in result
+            title = result["suggested_title"]
+            assert isinstance(title, str)
+            assert len(title) > 0
+            assert len(title) <= 60
+            # Should be exactly: "tool_name: error_message"
+            assert title == "ha_call_service: Service not found"
+
+    @pytest.mark.asyncio
+    async def test_bug_report_suggested_title_no_errors(
+        self, ha_report_issue_func, mock_client
+    ):
+        """Test title generation when there are no errors."""
+        mock_client.get_config.return_value = {"version": "2024.12.0"}
+        mock_client.get_states.return_value = []
+
+        with patch(
+            "ha_mcp.tools.tools_bug_report.get_recent_logs"
+        ) as mock_get_logs:
+            mock_get_logs.return_value = [
+                {
+                    "timestamp": "2024-12-01T10:00:00",
+                    "tool_name": "ha_get_state",
+                    "success": True,
+                    "execution_time_ms": 100,
+                },
+            ]
+
+            result = await ha_report_issue_func()
+
+            # Should still generate a generic title
+            assert "suggested_title" in result
+            title = result["suggested_title"]
+            assert isinstance(title, str)
+            assert len(title) > 0
+            assert len(title) <= 60
+
+    @pytest.mark.asyncio
+    async def test_bug_report_duplicate_check_urls(self, ha_report_issue_func, mock_client):
+        """Test that duplicate check URLs are generated with correct keywords."""
+        mock_client.get_config.return_value = {"version": "2024.12.0"}
+        mock_client.get_states.return_value = []
+
+        with patch(
+            "ha_mcp.tools.tools_bug_report.get_recent_logs"
+        ) as mock_get_logs:
+            mock_get_logs.return_value = [
+                {
+                    "timestamp": "2024-12-01T10:00:00",
+                    "tool_name": "ha_call_service",
+                    "success": False,
+                    "execution_time_ms": 50,
+                    "error_message": "Connection timeout",
+                },
+            ]
+
+            result = await ha_report_issue_func()
+
+            # Check duplicate check URLs are present
+            assert "duplicate_check_urls" in result
+            urls = result["duplicate_check_urls"]
+            assert isinstance(urls, list)
+            assert len(urls) > 0
+            # All URLs should be GitHub issue search URLs
+            for url in urls:
+                assert "github.com/homeassistant-ai/ha-mcp/issues" in url
+                assert "is%3Aissue" in url
+
+            # Verify keywords are in URLs
+            url_content = "".join(urls)
+            assert "ha_call_service" in url_content
+            assert "connection" in url_content
+            assert "timeout" in url_content
+
+    @pytest.mark.asyncio
+    async def test_bug_report_updated_instructions(
+        self, ha_report_issue_func, mock_client
+    ):
+        """Test that instructions include new workflow steps."""
+        mock_client.get_config.return_value = {"version": "2024.12.0"}
+        mock_client.get_states.return_value = []
+
+        result = await ha_report_issue_func()
+
+        instructions = result["instructions"]
+        # Check for new workflow steps
+        assert "Check for duplicates FIRST" in instructions
+        assert "duplicate_check_urls" in instructions
+        assert "suggested_title" in instructions
+        assert "markdown code block" in instructions.lower()
+        assert "```markdown" in instructions
+        assert "PROMINENTLY display the submission URL" in instructions