RAG Implementation

roboco/mcp/tasks/handlers/_helpers.py

@@ -113,6 +113,7 @@ def check_blocking_tasks(active_tasks: list[dict]) -> dict[str, Any] | None:
             f"You have a {status} task: {blocking[0]['id']}. "
             "Work on it first, or pause it if blocked.",
             {"active_task_id": blocking[0]["id"], "status": status},
+            hint="roboco_kb_search('task pause blocked')",
         )
     return None
 
@@ -162,6 +163,7 @@ async def validate_task_claimable(
             f"Cannot claim task in '{task_status}' status. "
             f"Your role ({agent_role}) can claim: {', '.join(allowed)}.",
             {"current_status": task_status, "allowed_statuses": allowed},
+            hint="roboco_kb_search('task claim role')",
         )
     return None
 
@@ -240,6 +242,7 @@ async def validate_task_ownership(
             "NOT_OWNER",
             "You are not assigned to this task",
             {"assigned_to": assigned_to},
+            hint="roboco_kb_search('task assignment ownership')",
         )
     return None
 

roboco/mcp/tasks/handlers/lifecycle.py

@@ -28,6 +28,7 @@ def _validate_documenter_role(agent_id: str) -> dict[str, Any] | None:
             "NOT_DOCUMENTER",
             "Only documenters can mark documentation as complete.",
             {"your_role": agent_role},
+            hint="roboco_kb_search('task lifecycle role permissions')",
         )
     return None
 
@@ -40,6 +41,7 @@ def _validate_pm_role(agent_id: str, action: str) -> dict[str, Any] | None:
             "NOT_AUTHORIZED",
             f"Only PMs and board members can {action}",
             {"your_role": role},
+            hint="roboco_kb_search('pm role permissions')",
         )
     return None
 
@@ -137,22 +139,7 @@ async def _check_descendants_completed(
                 },
             )
 
-        # Check for cancelled (need force override)
-        cancelled = [task for task in descendants if task.get("status") == "cancelled"]
-
-        if cancelled:
-            return format_error_response(
-                "CANCELLED_DESCENDANTS",
-                f"Task has {len(cancelled)} cancelled descendant(s).",
-                {
-                    "cancelled_count": len(cancelled),
-                    "guidance": (
-                        "Use force_with_cancelled=True with justification (CEO only) "
-                        "to complete despite cancelled descendants."
-                    ),
-                },
-            )
-
+        # All descendants in terminal states (completed/cancelled) - allow completion
         return None
     except Exception:
         return None
@@ -189,6 +176,7 @@ def _validate_completion_status(
         f"Cannot complete task in '{current_status}' status. "
         "Expected 'awaiting_pm_review' (dev work) or 'in_progress' (own task).",
         {"current_status": current_status},
+        hint="roboco_kb_search('task status lifecycle')",
     )
 
 

roboco/mcp/tasks/handlers/review.py

@@ -31,6 +31,7 @@ def _validate_developer_role(agent_id: str) -> dict[str, Any] | None:
             "Only developers can submit work for verification/QA. "
             "PMs should use roboco_task_complete() directly.",
             {"your_role": agent_role, "allowed_roles": ["developer"]},
+            hint="roboco_kb_search('developer workflow submit qa')",
         )
     return None
 
@@ -72,6 +73,7 @@ async def _validate_verification_submission(
             "NO_WORK_EVIDENCE",
             "No evidence of work found. Add commits with roboco_task_add_commit "
             "or update progress with roboco_task_progress before verification.",
+            hint="roboco_kb_search('task progress commits')",
         )
 
     return task, None
@@ -152,9 +154,12 @@ async def _save_notes_and_submit(
     return format_task_response(
         qa_resp.json(),
         "WAIT_FOR_QA",
-        "Task submitted for QA review.\n"
-        "You will be notified of the result.\n"
-        "In the meantime, call roboco_task_scan for other work.",
+        "Task submitted for QA review.\n\n"
+        "WHAT HAPPENS NEXT:\n"
+        "- QA will review your work and either PASS or FAIL\n"
+        "- If PASS: goes to documentation, then PM review\n"
+        "- If FAIL: returns to you with feedback for revision\n\n"
+        "Call roboco_task_scan for other work while waiting.",
     )
 
 
@@ -188,6 +193,7 @@ def _validate_qa_role(agent_id: str, action: str) -> dict[str, Any] | None:
             "NOT_QA",
             f"Only QA agents can {action} tasks in QA review.",
             {"your_role": agent_role},
+            hint="roboco_kb_search('qa workflow pass fail')",
         )
     return None
 
@@ -200,7 +206,11 @@ async def _check_self_review(
     original_dev = extract_original_developer(quick_context)
     agent_uuid = await resolve_agent_uuid_cached(agent_id, client)
     if agent_uuid and not can_review_task(agent_uuid, original_dev):
-        return format_error_response("SELF_REVIEW", "Cannot review your own work.")
+        return format_error_response(
+            "SELF_REVIEW",
+            "Cannot review your own work.",
+            hint="roboco_kb_search('self review prevention')",
+        )
     return None
 
 

roboco/mcp/tasks/handlers/work.py

@@ -148,6 +148,11 @@ async def handle_task_progress(
     if not progress_resp.ok:
         return format_error_response("UPDATE_FAILED", "Failed to update progress")
 
-    return format_task_response(
-        progress_resp.json(), "CONTINUE", "Progress recorded. Keep working."
+    guidance = (
+        "Progress recorded. Keep working.\n\n"
+        "TIPS:\n"
+        "- Use roboco_journal_entry() to log decisions as you go\n"
+        "- Hit an error? Try roboco_search_error(pattern) for solutions\n"
+        "- Need context? Use roboco_kb_search(query) to find related code/docs"
     )
+    return format_task_response(progress_resp.json(), "CONTINUE", guidance)

roboco/mcp/utils.py

@@ -62,6 +62,7 @@ def format_error_response(
     code: str,
     message: str,
     details: dict[str, Any] | None = None,
+    hint: str | None = None,
 ) -> dict[str, Any]:
     """
     Format a standardized error response for MCP tools.
@@ -72,13 +73,14 @@ def format_error_response(
         code: Error code (e.g., "NOT_FOUND", "API_ERROR", "PERMISSION_DENIED")
         message: Human-readable error message
         details: Optional additional error details
+        hint: Optional RAG search suggestion for finding solutions
 
     Returns:
         Standardized error response dict with status="error"
     """
     from roboco.api.schemas.common import error_response
 
-    return error_response(code, message, details)
+    return error_response(code, message, details, hint)
 
 
 def format_success_response(