feat(rag): pre-generation validated-extractive short-circuit for routine procedural queries (E-3c PR-B)

[BigSimmo]

Summary

E-3c PR-B — kills the measured 6× wasted-generation class from baseline run #57: fast-model attempts on routine procedural queries ("What is the process for ECT?", "What should a patient safety plan include?") that fail the answer quality gate and get replaced by the deterministic extractive answer anyway, burning seconds and tokens for nothing.

The fix generalizes the codebase's own proven pattern (the LAI and blocked-recovery short-circuits): when such a query's extractive candidate independently passes the complete final-gate stack (finalizeRagAnswerQuality — core quality + claim support + numeric verification), the route flips to extractive before generation (marker validated_routine_extractive_first). Scope is deliberately narrow: fast route + strong_routine_retrieval reason + passed confidence gate + source-backed + document_lookup/unsupported_or_general class only + "What…process/include/required" shape — dose, threshold, comparison, broad-summary, and "How is X managed" shapes all stay on model synthesis (pinned by negative tests).

The three existing predicates move byte-verbatim (machine-verified brace-diff) into new src/lib/rag/rag-extractive-first.ts, taking rag.ts from 5029 to 4908 lines against its 5030 no-growth budget.

Both reviewer subagents pre-push, no P0/P1:

• rag-retrieval-reviewer APPROVE-WITH-NITS: move fidelity byte-identical; confidence-gate skip proven a no-op for passed gates; markers pairwise mutually exclusive; comparison false-positives blocked by unchanged classifier precedence; zero retrieval/ranking/selection/threshold change. Its P2 — eval-only assertions unverifiable offline for flip candidates — is adopted as this PR's merge gate (below).
• clinical-governance-reviewer APPROVE-WITH-NITS: full gate-stack trace confirms nothing bypassed; citations from the same scoped evidence; conservative failure preserved. Its P2 (pre-existing cross-reference-with-overlap gap, not materially widened) is fixed in this PR as a disclosed post-review hardening: isBareCrossReferenceAnswer now screens every short-circuit path, strictly narrowing what can ship (discriminating test added; 61/61 green).

Merge gate — held as draft until the live pair is green. Per the standing lesson (offline-green + review-approved proven insufficient for this surface, 2026-07-20), a branch canary dispatch (ref = this branch, answer_case_limit=44 + answer_quality_eval=true, ~$3–6 of the user-approved envelope) runs the full answer-side pair against the banked #57/#58 baselines before this merges. Green = zero per-case regressions, recalls pinned 1.0, quality/targeting rates ≥ baseline, and the 6 target cases showing the short-circuit marker.

RAG impact: behaviour change — canary pair: baselines #57 (29786560936) / #58 (29788404357) → branch run (dispatching now; result recorded here before ready-for-review). Answer routing only; retrieval, ranking, selection, and thresholds untouched (adversarially verified).

Verification

• Red-proof fails on prior code two independent ways (model-not-called + marker-nonexistent)
• Negative guards: "How is…" shape, gate-failing candidate, dose-class query all stay on model synthesis; existing LAI/blocked-recovery tests byte-identical
• Focused: rag-extractive-first 11/11 (incl. the hardening test) + rag-answer-fallback 50/50; offline/contract suites green
• npm run test — 3061 passed / 1 known container-only pdf artifact
• typecheck, lint, prettier, maintainability budget (4908/5030) — clean
• Branch canary pair vs #57/[WIP] Refactor monolithic front‑end and decouple domain logic #58 — pending; merge-gating

Risk and rollout

• Risk: medium — clinician-visible answer-content change on ~6+ query shapes (model prose → gate-validated fact synthesis). Bounded by the full gate stack running on every shipped candidate, the narrow trigger, and the live pair before merge. Flip-risk cases enumerated by review: quality-nocc-document-support, quality-form-required-documentation, quality-discharge-documentation, quality-duress-pathway + rag-set siblings.
• Rollback: single revert (module move is mechanical). Evals run skipCache; runtime cached answers age out via TTL.
• Provider or production effects: the branch canary dispatch (~$3–6, user-authorized envelope). No schema/env changes.

Clinical Governance Preflight

• Source-backed claims still require linked source verification before clinical use — short-circuited answers pass the identical claim-support + numeric-verification + final-quality stack (reviewer-traced)
• No patient-identifiable document workflow was introduced or expanded
• Supabase target remains Clinical KB Database (sjrfecxgysukkwxsowpy) — no access changes
• Service-role keys and private document access remain server-only
• Demo/synthetic content remains clearly separated from real clinical sources
• Source metadata, review status, and outdated/unknown-source behavior remain conservative
• Deployment classification/TGA SaMD impact was checked: answer text on routine procedural queries shifts from model prose to gate-validated extractive synthesis — governance-reviewed, live-pair-gated before merge

🤖 Generated with Claude Code

https://claude.ai/code/session_01EXsJcLrbZUXwnBeG91cVo9

---

Generated by Claude Code

Summary by CodeRabbit

• New Features

  • Routine procedural questions can now receive validated, citation-backed answers directly from retrieved content without unnecessary generation.
  • Added safeguards to prevent unsupported or bare cross-reference answers from being returned.
  • Certain medication dose-risk questions continue through model synthesis for appropriate handling.

• Bug Fixes

  • Reduced unnecessary answer generation for eligible extractive responses.
  • Improved routing consistency across retrieval confidence outcomes.

• Tests

  • Added coverage for procedural routing, validation failures, cross-reference handling, and medication safety scenarios.

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds centralized validated extractive short-circuit predicates, integrates them into RAG routing before generation, and adds coverage for procedural, recovery, LAI-management, cross-reference, and medication dose-risk cases.

Changes

Validated extractive routing

Layer / File(s)	Summary
Short-circuit predicates src/lib/rag/rag-extractive-first.ts	Defines grounding validation, query-shape checks, eligibility predicates, and fixed precedence for extractive short-circuit selection.
RAG routing integration src/lib/rag/rag.ts	Uses the shared selector to force validated extractive routing with no model, while retaining the existing confidence gate when no short-circuit applies.
Routing regression coverage tests/rag-extractive-first.test.ts, tests/rag-answer-fallback.test.ts, docs/branch-review-ledger.md	Tests procedural routing, generation fallback, cross-reference rejection, medication dose-risk exclusions, and records the review verification entry.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant RAGRequest
  participant RAGRouting
  participant ExtractiveSelector
  participant TextGeneration
  RAGRequest->>RAGRouting: submit query and retrieval results
  RAGRouting->>ExtractiveSelector: evaluate route, source backing, and gate status
  ExtractiveSelector-->>RAGRouting: reason marker or null
  alt validated extractive candidate
    RAGRouting-->>RAGRequest: return extractive grounded answer
  else no validated candidate
    RAGRouting->>TextGeneration: generateStructuredTextResult
    TextGeneration-->>RAGRequest: return synthesized answer
  end

Loading

Possibly related PRs

• BigSimmo/Database#607: Related RAG answer routing and extractive fallback behavior.
• BigSimmo/Database#845: Related extractive short-circuit validation and retrieval-gating changes.

Suggested labels: codex

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main change: a validated-extractive short-circuit for routine procedural RAG queries.
Description check	✅ Passed	The description matches the template well, covering Summary, Verification, Risk and rollout, and Clinical Governance Preflight; only Notes is absent.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/clinical-kb-pwa-review-asi3wb

---

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.