feat: /recce-analyze + intent routing + Codex parity (M1, M4)

AGENTS.md

@@ -2,6 +2,71 @@
 
 This project uses **bd** (beads) for issue tracking. Run `bd onboard` to get started.
 
+## PR Impact Analysis (One-Sentence Trigger)
+
+<!-- Codex AGENTS.md convention v2026-05 — pinned at cascade-003 implementation (R6) -->
+
+Any of the following natural-language phrases MUST trigger the full
+bootstrap-and-analysis flow below. Execute immediately without asking for
+confirmation when one of these phrases is detected in a dbt project directory.
+
+**Canonical trigger phrases:**
+- "summarize the impact of my changes"
+- "summarize my PR impact"
+- "what changed vs main"
+- "data diff for this branch"
+- "review my changes" (in dbt project context)
+- "show me what broke"
+- "compare my branch to main"
+- "what models did I change"
+- "run recce"
+- "check my dbt changes"
+
+### Orchestration Steps (Codex path, mirrors recce-analyze.md steps 3–7)
+
+Assumes prerequisites (dbt, recce installed; dbt_project.yml present) and branch
+detection are already satisfied. Adapt `${CLAUDE_PLUGIN_ROOT}` to the Codex
+equivalent plugin root path.
+
+**Step 3 — Base strategy:**
+```bash
+recce check-base --format json
+```
+Parse `recommendation`:
+- `reuse` → proceed to Step 4.
+- `docs_generate` → warn "_⚠️ Base artifacts are stale. Refreshing…_" (AC-3);
+  run `dbt docs generate --target-path target-base`; proceed to Step 4.
+- `full_build` → `git stash; git checkout <base>; dbt build --target-path target-base; git checkout <target>; git stash pop`.
+
+**Step 4 — Target artifacts:**
+```bash
+ls target/manifest.json 2>/dev/null || echo MISSING
+```
+If missing → `dbt docs generate`.
+
+**Step 5 — Start MCP server:**
+```bash
+bash ${CODEX_PLUGIN_ROOT}/scripts/start-mcp.sh
+```
+Verify `STATUS=STARTED` or `STATUS=ALREADY_RUNNING` before continuing.
+
+**Step 6 — Analysis (call MCP tools in order):**
+1. `impact_analysis` — fast summary first.
+2. `lineage_diff` — model-level changes.
+3. `schema_diff` — column structure changes.
+4. `row_count_diff` with `select: "config.materialized:table"` — tables only.
+
+**Step 7 — Output:**
+Render a four-section markdown report:
+```
+## Impact Summary        ← narrative from impact_analysis
+## Lineage Changes       ← from lineage_diff
+## Schema Changes        ← table from schema_diff
+## Row Count Changes     ← table from row_count_diff
+```
+All four sections MUST appear. Write _"No changes detected."_ for empty
+sections. Log elapsed time; warn if > 120 s.
+
 ## Quick Reference
 
 ```bash

plugins/recce-quickstart/commands/recce-analyze.md

@@ -0,0 +1,171 @@
+---
+name: recce-analyze
+description: One-shot Recce setup + PR impact analysis
+---
+
+# Recce Analyze — One-Shot PR Impact
+
+Run this single command to bootstrap your Recce environment and produce a
+complete PR-impact summary. No separate setup step required.
+
+Record the wall-clock start time at the beginning of Step 1 and log total
+elapsed time after Step 7.
+
+---
+
+## Step 1: Prerequisites
+
+Run the following checks before proceeding. If any fail, help the user resolve
+them before continuing.
+
+```bash
+# 1a. Confirm this is a dbt project
+ls dbt_project.yml
+```
+
+- If `dbt_project.yml` is **not found**: Tell the user this is not a dbt project
+  directory. Ask them to navigate to their project root.
+
+```bash
+# 1b. Confirm required tools are available
+dbt --version
+python --version || python3 --version
+recce --version
+```
+
+- If `dbt` is missing: guide the user through adapter-specific installation
+  (`pip install dbt-<adapter>`).
+- If `recce` is missing: run `pip install recce`.
+- Continue once all three tools are present.
+
+---
+
+## Step 2: Branch Detection
+
+```bash
+git branch --show-current
+```
+
+Determine the **target branch** (current) and **base branch**:
+
+- If current branch is `main` or `master`: ask the user which feature branch to
+  compare against.
+- Otherwise: target = current branch; base = `main` or `master` (check which
+  exists via `git branch --list main master`).
+
+Present the detected configuration to the user and confirm before proceeding.
+
+---
+
+## Step 3: Base Strategy
+
+```bash
+recce check-base --format json
+```
+
+Parse the JSON response and branch on `recommendation`:
+
+| `recommendation` | Action |
+|---|---|
+| `reuse` | Skip artifact generation — base artifacts are fresh. |
+| `docs_generate` | Warn user about staleness; run `dbt docs generate --target-path target-base` to refresh. Emit: _"⚠️ Base artifacts are stale. Refreshing with dbt docs generate…"_ (AC-3) |
+| `full_build` | Run the full base build (see below). |
+
+**Full base build** (only for `full_build`):
+```bash
+git stash
+git checkout <base-branch>
+dbt build --target-path target-base
+git checkout <target-branch>
+git stash pop
+```
+
+---
+
+## Step 4: Target Artifacts
+
+```bash
+ls target/manifest.json 2>/dev/null || echo MISSING
+```
+
+- If `target/manifest.json` is **missing**: run `dbt docs generate`.
+- If present: reuse existing target artifacts.
+
+---
+
+## Step 5: Start MCP Server
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/scripts/start-mcp.sh
+```
+
+Parse the output:
+
+- `STATUS=STARTED` or `STATUS=ALREADY_RUNNING`: continue.
+- `ERROR=*`: show the error and the fix suggestion from `start-mcp.sh` output.
+  Do not proceed until the server is running.
+
+---
+
+## Step 6: Analysis — Call MCP Tools in Order
+
+Call each tool in sequence. Collect all four results before composing the
+output.
+
+1. **`mcp__recce__impact_analysis`** — fast impact summary (call first; no
+   parameters needed for the default scope).
+2. **`mcp__recce__lineage_diff`** — model-level lineage changes.
+3. **`mcp__recce__schema_diff`** — column structure changes.
+4. **`mcp__recce__row_count_diff`** with selector
+   `select: "config.materialized:table"` — row count changes on tables only
+   (never views; they trigger expensive queries).
+
+---
+
+## Step 7: Output — Compose Markdown Summary
+
+Render the following four-section markdown report using the data collected in
+Step 6. All four sections MUST appear even if a section has no changes (write
+_"No changes detected."_ in that case).
+
+```markdown
+## Impact Summary
+
+<narrative paragraph from impact_analysis result>
+
+## Lineage Changes
+
+<list or DAG of modified models and their change_status from lineage_diff>
+
+## Schema Changes
+
+| Model | Change Type | Details |
+|-------|-------------|---------|
+<rows from schema_diff result>
+
+## Row Count Changes
+
+| Model | Base | Current | Change |
+|-------|------|---------|--------|
+<rows from row_count_diff result>
+```
+
+After rendering the report, log total elapsed time (Step 1 → Step 7). If
+elapsed time exceeds 120 s, append a note:
+_"⏱ Analysis took <N> s. Consider pre-generating base artifacts to speed up
+future runs."_
+
+---
+
+## Error Recovery
+
+If the MCP server fails to start, check the log:
+
+```bash
+cat /tmp/recce-mcp-server.log
+```
+
+Common issues:
+- Database connection errors: check `profiles.yml`.
+- Missing artifacts: re-run the relevant artifact generation step.
+- Port conflicts: set `RECCE_MCP_PORT` to a different port.

plugins/recce-quickstart/commands/recce-pr.md

@@ -7,6 +7,9 @@ args:
     required: false
 ---
 
+> **Deprecated (as of 003-pre-pr-one-sentence):** Use `/recce-analyze` for setup + analysis
+> in one command. `/recce-pr` remains available if the MCP server is already running.
+
 # Recce PR Analysis
 
 Analyze the data impact of a Pull Request using Recce MCP tools.

plugins/recce-quickstart/commands/recce-setup.md

@@ -3,6 +3,9 @@ name: recce-setup
 description: Guided setup for Recce environment in a dbt project
 ---
 
+> **Deprecated (as of 003-pre-pr-one-sentence):** Use `/recce-analyze` for one-shot
+> setup + analysis. `/recce-setup` remains available for step-by-step setup only.
+
 # Recce Setup - Guided Environment Configuration
 
 You are helping the user set up Recce in their dbt project. Follow these steps in order, checking each prerequisite before proceeding.

plugins/recce-quickstart/skills/recce-guide/SKILL.md

@@ -18,14 +18,36 @@ Activate this skill when you detect:
 4. **dbt command execution** - User runs `dbt run`, `dbt build`, `dbt test`
 5. **Data quality questions** - User asks about data validation, data quality, testing data
 
+### Canonical Trigger Phrases (route to `/recce-analyze`)
+
+The following phrases MUST trigger the merged bootstrap. Respond to any of the
+below by invoking `/recce-analyze` immediately, without asking for confirmation.
+
+- "summarize the impact of my changes"
+- "summarize my PR impact"
+- "what changed vs main"
+- "data diff for this branch"
+- "review my changes" (in dbt project context)
+- "show me what broke"
+- "compare my branch to main"
+- "what models did I change"
+- "run recce"
+- "check my dbt changes"
+
 ## Available Commands
 
 When in a dbt project, inform the user about these commands:
 
-- `/recce-setup` - One-click environment setup for Recce
-- `/recce-pr` - Analyze PR data impact
+- `/recce-analyze` - **One-shot setup + PR impact analysis** (primary command)
 - `/recce-check` - Run data validation checks
 
+### Legacy commands
+
+These commands remain available but are superseded by `/recce-analyze`:
+
+- `/recce-setup` - Step-by-step guided setup only
+- `/recce-pr` - PR analysis when the MCP server is already running
+
 ## Available Recce MCP Tools
 
 When Recce MCP Server is running (check with `bash ${CLAUDE_PLUGIN_ROOT}/scripts/check-mcp.sh`):

pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "recce-claude-plugin-tests"
+version = "0.1.0"
+description = "Test suite for recce-claude-plugin"
+requires-python = ">=3.10"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]

tests/fixtures/trigger_phrases.txt

@@ -0,0 +1,10 @@
+summarize the impact of my changes
+summarize my PR impact
+what changed vs main
+data diff for this branch
+review my changes
+show me what broke
+compare my branch to main
+what models did I change
+run recce
+check my dbt changes