feat(recce-review): pre-flight check for missing recce install

plugins/recce/hooks/scripts/session-start.sh

@@ -65,7 +65,7 @@ else
     echo "MCP_READY=false"
     if [ "$RECCE_INSTALLED" != "true" ]; then
         echo "MCP_SKIP_REASON=recce not installed"
-        echo "FIX=Activate your venv or run: pip install recce"
+        echo "FIX=Activate your venv or run: pip install 'recce[mcp]'"
     elif [ "$TARGET_EXISTS" != "true" ]; then
         echo "MCP_SKIP_REASON=no target/manifest.json"
         echo "FIX=Run: dbt docs generate"

plugins/recce/skills/recce-review/SKILL.md

@@ -26,6 +26,31 @@ Follow these steps in order.
 
 ---
 
+## Pre-flight: Verify `recce` is installed
+
+Before any other step, confirm the `recce` CLI is available on this machine. The MCP server is launched by Claude Code via stdio (`run-mcp-stdio.sh`) and silently fails to start if `recce` is missing — the user only finds out when a tool call errors out mid-review. Catch it here instead.
+
+Run:
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/skills/recce-review/scripts/check-recce-installed.sh
+```
+
+The script auto-activates a local `venv/` or `.venv/` (mirroring `run-mcp-stdio.sh`) and prints `RECCE=ready` (with `RECCE_VIA` and `RECCE_VERSION`) or `RECCE=missing`.
+
+- `RECCE=ready` — continue to Step 0.
+- `RECCE=missing` — tell the user, verbatim, then **stop**:
+
+  > `recce` is not installed in this environment, so the Recce MCP server can't start and `/recce-review` can't run.
+  >
+  > To install:
+  > - If your dbt project uses a virtualenv, activate it first (e.g. `source .venv/bin/activate`), then re-run `/recce-review`.
+  > - Otherwise install Recce: `pip install 'recce[mcp]'` (or `uv pip install 'recce[mcp]'`), then restart Claude Code so the MCP server picks up the new binary, and re-run `/recce-review`.
+
+  Do not attempt to install `recce` automatically — environment choices (venv vs. system, pip vs. uv vs. poetry) belong to the user.
+
+---
+
 ## Step 0: Cloud-mode resolution (only if user provided a relevant URL or asked for cloud review)
 
 > Skip this step if the user did not provide a PR/MR URL, a Cloud session/launch URL, a bare UUID, and did not mention "cloud", "cloud session", or "Recce Cloud".

plugins/recce/skills/recce-review/scripts/check-recce-installed.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+# Probe whether `recce` is available on PATH, mirroring the venv auto-detection
+# used by run-mcp-stdio.sh so the skill check matches the MCP server launcher.
+# Prints exactly one of:
+#   RECCE=ready        (with RECCE_VIA=venv|system and RECCE_VERSION=<version>)
+#   RECCE=missing
+# Always exits 0.
+set -u
+
+for VENV_DIR in venv .venv; do
+    if [ -f "$VENV_DIR/bin/activate" ]; then
+        # shellcheck disable=SC1091
+        source "$VENV_DIR/bin/activate"
+        RECCE_VIA=venv
+        break
+    fi
+done
+
+if command -v recce >/dev/null 2>&1; then
+    echo "RECCE=ready"
+    echo "RECCE_VIA=${RECCE_VIA:-system}"
+    VERSION=$(recce --version 2>/dev/null | head -1 | awk '{print $NF}')
+    [ -n "$VERSION" ] && echo "RECCE_VERSION=$VERSION"
+else
+    echo "RECCE=missing"
+fi
+
+exit 0